Skip to content
Skip to Content
Batchwell Docs

Migrate from the OpenAI SDK

Move an OpenAI SDK app to Batchwell by changing the base URL and API key, then check the few request fields Batchwell rejects.

To move an app that uses the OpenAI SDK to Batchwell, change two values: set the base URL to https://api.batchwell.ai/v1 and use a Batchwell API key. Batchwell accepts the OpenAI Chat Completions format at POST /v1/chat/completions, so the code around the call stays the same unless it sends a field listed under what Batchwell rejects.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.batchwell.ai/v1",
    api_key=os.environ["BATCHWELL_API_KEY"],
)

resp = client.chat.completions.create(
    model="batchwell/kimi-k3.1-pro-uncensored",
    messages=[{"role": "user", "content": "Say hello in one short sentence."}],
)
print(resp.choices[0].message.content)

Both snippets read the key from the BATCHWELL_API_KEY environment variable, so no key is written into your code. A Batchwell key starts with bw_live_ or bw_test_; see Authentication and the Quickstart for creating one.

Send a Batchwell model id as model. The snippets use batchwell/kimi-k3.1-pro-uncensored, a model Batchwell serves today. Every id you can send is listed by GET /v1/models and on the models page; see models for the fields.

Batchwell accepts only the accepted fields and answers 400 instead of dropping a field it does not support. Check your calls for these:

  • n greater than 1, logprobs and top_logprobs are rejected with 400 unsupported_parameter.
  • Any other field gets 400 unsupported_parameter, and the error message names the field.
  • Message content must be text. Parts of type image_url, input_audio or file get 400 unsupported_content.
  • A reasoning_effort value outside none, minimal, low, medium, high, xhigh and max gets 400 invalid_parameter. See reasoning effort.

The accepted fields and the full rules are on chat completions.

  • usage.cost_micro is the amount charged for the request, in micro-USD (1,000,000 = $1). Rarely the charge is not final when the response is sent (the model's final usage arrived after the request was handed to billing reconciliation): usage then has cost_pending: true and no cost_micro, and the charge, the final metered cost, shows on the generation (GET /v1/generation) once settled, within 30 minutes.
  • choices[].message.batchwell holds generation_id, model, model_used, provider and ai_generated, a machine-readable marker that the content is AI-generated. model is the id you requested and model_used is the model that answered; they differ after a fallback. provider is always batchwell.
  • The response headers x-batchwell-generation-id and x-batchwell-model name the generation and the model that answered. A stream that opened before the model was known carries the requested id in x-batchwell-model, so read batchwell.model_used there. Use the id with generation lookup.

Add a models array of up to 5 model ids and Batchwell tries them in order if model cannot serve the request. Fallback happens only before any output reaches you. Routing has the details and the routing preferences you can send in provider.

Set "stream": true as you would with the OpenAI SDK. The stream ends with a usage chunk that carries cost_micro, then data: [DONE]; see streaming.

  • Chat completions lists the accepted fields.
  • Routing covers fallback models and routing preferences.
  • Errors lists every error code and what to do about it.