SDKs and API formats
Anthropic compatibility
Use the Anthropic SDK and tools like Claude Code with Inworld Inference through Anthropic-compatible endpoints.
Use the Anthropic SDK and tools like Claude Code with Inworld Inference's Anthropic-compatible endpoints. You get multi-provider routing, fallbacks, and cost optimization through the same interface.
Credential handling
Run these examples on your server. Set INWORLD_API_KEY to the complete Base64 credentials copied from Portal or the CLI, without encoding them again. The examples set an explicit Authorization: Basic ... header. Browser/mobile clients need a backend-minted token, never the server API key.
Endpoints
The Anthropic-compatible endpoints are:
| Endpoint | Purpose |
|---|---|
POST https://api.inworld.ai/v1/messages | Create a message, streaming or not |
POST https://api.inworld.ai/v1/messages/count_tokens | Count input tokens |
When using the Anthropic SDK, set the base URL to https://api.inworld.ai. The SDK automatically appends the /v1/messages paths.
Authentication
For a direct HTTP request, use the copied Base64 credential with Basic:
Authorization: Basic <base64-credential>In the SDK examples below, auth_token / authToken gives the SDK your credential, which it sends as Authorization: Bearer .... Inworld Inference accepts the credential as Bearer as well as Basic, so this setting alone authenticates. The default_headers / defaultHeaders setting switches the header to Basic, to match direct HTTP requests; it is optional.
The x-api-key header is not read, so an Anthropic-style api_key / ANTHROPIC_API_KEY setup fails authentication. The examples also keep an Anthropic key in your environment from being sent to Inworld:
- Python:
api_key=Nonestill readsANTHROPIC_API_KEYfrom the environment, so the example also removes theX-Api-Keyheader withanthropic.omit. - TypeScript: passing
authTokenandapiKey: nullstops the SDK from readingANTHROPIC_API_KEY, so no extra header setting is needed.
Anthropic SDK
Send a request with Anthropic's SDK:
import os
import anthropic
api_key = os.environ["INWORLD_API_KEY"]
client = anthropic.Anthropic(
base_url="https://api.inworld.ai",
api_key=None,
auth_token=api_key,
default_headers={"Authorization": f"Basic {api_key}", "X-Api-Key": anthropic.omit},
)
message = client.messages.create(
model="inworld/<router-id>",
max_tokens=1024,
messages=[
{"role": "user", "content": "Explain how neural networks learn."}
]
)
print(message.content[0].text)import Anthropic from '@anthropic-ai/sdk';
const apiKey = process.env.INWORLD_API_KEY;
if (!apiKey) throw new Error('Set INWORLD_API_KEY to your copied Base64 credential');
const client = new Anthropic({
baseURL: 'https://api.inworld.ai',
apiKey: null,
authToken: apiKey,
defaultHeaders: { Authorization: `Basic ${apiKey}` },
});
const message = await client.messages.create({
model: 'inworld/<router-id>',
max_tokens: 1024,
messages: [
{ role: 'user', content: 'Explain how neural networks learn.' }
],
});
console.log(message.content[0].text);Response
The response follows the Anthropic Messages API format:
{
"content": [
{"text": "Neural networks learn through...", "type": "text"}
],
"id": "msg-...",
"model": "anthropic/claude-opus-4-6",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 12,
"output_tokens": 150,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0
},
"metadata": {
"attempts": [
{"model": "anthropic/claude-opus-4-6", "success": true, "time_to_first_token_ms": 1152}
],
"generation_id": "019b...",
"total_duration_ms": 1480,
"reasoning": "Using specified model: 'anthropic/claude-opus-4-6' - success"
}
}On non-streaming responses, Inworld Inference adds a metadata field containing routing information — attempt history, timing, and, when applicable, route_id, variant_id, and reasoning. This field is not part of the standard Anthropic response format, but it does not break Anthropic SDK parsing.
Supported and unsupported features
/v1/messages translates each request into the router's chat format, routes it, and translates the result back. Fields and content blocks that have no translation are dropped silently, without an error.
Request parameters
| Supported | Notes |
|---|---|
model, messages, max_tokens, stream | model accepts provider/model (a model's id in List models; use one whose endpoints includes /v1/messages), a bare Claude name, auto, or inworld/<router-id> |
system | String or array of text blocks; multiple blocks are joined with a space unless a block carries cache_control |
temperature, top_p, stop_sequences | |
tools | Tools use name, description, input_schema, and cache_control. strict is passed on to models that support strict tool use and dropped for the others. "format": "uri" is removed from input schemas, and a tool named BatchTool is dropped |
tool_choice | auto, none, any, and tool are supported; any is sent as required. disable_parallel_tool_use is sent as parallel_tool_calls (true becomes false). An unknown type returns 400 |
metadata | metadata.user_id is used as the end-user ID |
cache_control | Top-level, and on system, message, content, and tool blocks |
thinking | type (enabled with budget_tokens, adaptive, disabled, or between_tools) and display. If the selected model doesn't take that type, the router sends the nearest one it does and, on non-streaming responses, adds a warning to metadata.attempts[].warnings. On models from other providers, the type and budget become the model's reasoning setting |
output_config | format ({"type": "json_schema", "schema": {...}}) becomes structured output for any model that supports it; a malformed format returns 400. effort becomes the reasoning effort, except when thinking.type is disabled |
The router extensions models, sort, ignore, reasoning, prompt_variables, and session are accepted as top-level fields. To send other router extensions, such as provider or web_search_options, nest them in an extra_body object in the JSON body. The Anthropic SDK's extra_body option adds its keys at the top level, so pass the top-level extensions directly and nest the others one level deeper, as in extra_body={"extra_body": {"provider": {...}}}:
message = client.messages.create(
model="anthropic/claude-opus-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
extra_body={
"models": ["openai/gpt-5.4", "google-ai-studio/gemini-2.5-flash"],
"sort": ["price"],
},
)Refused: audio, top level or in extra_body, returns 400 with code: "unsupported_parameter", because an Anthropic response has no audio block. For voice responses, use LLM + TTS on /v1/chat/completions.
Dropped: top_k, service_tier, mcp_servers, container, the older beta output_format field, and any other top-level field not listed above. The router forwards Anthropic server tools and special tool types (web search, code execution, computer use, and so on) as ordinary function definitions built from name, description, and input_schema. It does not execute them.
Content blocks
| Block type | Handling |
|---|---|
text | Converted. Multiple text blocks in one message are joined with a space, unless a block carries cache_control or the message contains an image; then they stay separate content parts |
image | Converted, from base64 or url sources. A url source must be an https, http or data URL, in a message or a tool_result. Any other scheme, such as gs://, returns 400; the message names the converted field, for example messages[0].content[1].image_url.url must be an https, http or data URL |
tool_use | Converted to a tool call. Repeated IDs within a message are de-duplicated |
tool_result | Converted to a tool message. Text blocks are joined with a newline, and images are kept. Models that can't read images in a tool result, because of their provider or because they are text-only, get the text only. is_error: true is passed on; providers without an error flag get the text prefixed with Error: |
document (including PDFs), search_result, thinking, redacted_thinking, server tool result blocks | Dropped |
Because thinking blocks in conversation history are dropped, multi-turn reasoning with tool calls does not round-trip thinking signatures.
Response differences
stop_sequenceis alwaysnull. When a stop sequence ends generation,stop_reasonisend_turn.- Non-streaming
stop_reasonisend_turn,tool_use, ormax_tokens. Streaming responses report onlyend_turnortool_use. - Reasoning output is returned as a
thinkingblock without asignature. - A non-streaming response always contains a
textblock, which is empty when the model only calls tools. A streaming response includes atextblock only when the model returns text. usagealways includescache_read_input_tokensandcache_creation_input_tokens, which are0when nothing was cached. As in Anthropic's API,input_tokenscounts only the prompt tokens that were neither read from nor written to the cache, so the whole prompt isinput_tokens+cache_read_input_tokens+cache_creation_input_tokens. Priceinput_tokensat the input rate and each cache count at its own rate; nothing is counted twice. A stream reports these counts in its finalmessage_deltaevent;message_startusually reports0. (On chat completions,prompt_tokensincludes cached tokens.)
Streaming
With stream: true, the response uses Anthropic's streaming events. While the model sends nothing after the stream has started, the router sends ping events at the keepalive interval, as Anthropic's API does, so idle connections stay open. The Anthropic SDKs ignore it; a hand-written parser should skip it.
Messages requests have the same time limits as chat completions, for one model attempt and for the whole request with its fallbacks.
Errors
Errors that the router raises before a response starts use the OpenAI-style error body with the matching HTTP status, not Anthropic's {"type": "error", ...} envelope:
{
"error": {
"message": "'model' field is required",
"type": "invalid_request_error"
}
}The Anthropic SDKs still raise the usual status-based exceptions, but code that parses the error body directly should read error.message and error.type. Errors during a stream are sent as an Anthropic error event with type api_error.
Authentication and permission errors (401, 403), and a 404 for an unknown path under /v1/messages, have a plain-text body such as Unauthorized instead.
Count tokens
POST /v1/messages/count_tokens returns the input token count for a request without generating a response:
curl -X POST https://api.inworld.ai/v1/messages/count_tokens \
-H "Authorization: Basic $INWORLD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-opus-4-6",
"messages": [
{"role": "user", "content": "Explain how neural networks learn."}
]
}'{"input_tokens": 14}The count is computed for the named model only, without routing or fallbacks. Keep these limits in mind:
modelis required and must be a specific model. A bare name is treated as an Anthropic model (claude-opus-4-6becomesanthropic/claude-opus-4-6).autoandinworld/<router-id>are not supported.- Only
model,messages,tools, andtool_choiceare read. The top-levelsystemprompt is not counted; to include it, add it as a message withrole: "system". - Only text is counted. For array content, the
textof each block is counted; images,tool_use, andtool_resultblocks are not. - Tools must use the OpenAI shape (
{"type": "function", "function": {"name", "description", "parameters"}}) to be counted. Anthropic-shaped tools (name,input_schema) are not counted accurately. - Errors: a missing
model, invalid JSON or an unknowntool_choicereturns400, and aContent-Typeother thanapplication/jsonreturns415. Any failure while counting, including an unknown model, returns500with typeapi_error.
Next Steps
- Claude Code Integration to use Inworld Inference as your Claude Code backend.
- Migrating from Anthropic for a step-by-step migration guide.