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.
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:
ngreater than 1,logprobsandtop_logprobsare rejected with400 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_audioorfileget400 unsupported_content. - A
reasoning_effortvalue outsidenone,minimal,low,medium,high,xhighandmaxgets400 invalid_parameter. See reasoning effort.
The accepted fields and the full rules are on chat completions.
usage.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):cost_micro usagethen hascost_pending: trueand nocost_micro, and the charge, the final metered cost, shows on the generation (GET /v1/generation) once settled, within 30 minutes.choices[].holdsmessage. batchwell generation_id,model,model_used,providerandai_generated, a machine-readable marker that the content is AI-generated.modelis the id you requested andmodel_usedis the model that answered; they differ after a fallback.provideris alwaysbatchwell.- The response headers
x-batchwell-generation-idandx-batchwell-modelname the generation and the model that answered. A stream that opened before the model was known carries the requested id inx-batchwell-model, so readbatchwell.there. Use the id with generation lookup.model_used
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.