Chat Completions

Create chat completion

Generate a response for the given chat conversation

POST/v1/chat/completions

Call hundreds of models from various providers directly through our unified API, or set model to auto for automatic model selection based on criteria like price, latency, or performance.

For more advanced routing — such as conditional routing, A/B testing across variants, and reusable configurations — create a router and reference it via the model field (e.g., inworld/my-router).

For web-grounded answers, use extra_body.web_search.

For voice output, see LLM + TTS, including optional word or character timestamps.

Authorizations

Authorizationstringrequired

Your authentication credentials. For Basic authentication, please populate Basic $INWORLD_API_KEY.

Please make sure your API Key has write permissions for the Router API in order to create, update, and delete routers. You can create a key in one command with the Inworld CLI: inworld workspace add-key.

Body

application/json

modelstringrequired

The model to use, which can be:

A model id (e.g., gpt-oss-120b). The best provider is automatically selected by latency, or you can control provider selection via extra_body.provider. See Models for available models.
A provider-prefixed model id (e.g., openai/gpt-5). This specifies the provider and model to use.
auto for automatic model selection based on criteria like price, latency, or intelligence
A router, which is specified by inworld/<router-name>. The router name must be prefixed by inworld/.

messagesobject[]required

A list of messages comprising the conversation so far.

If using a router where a prompt is specified, these messages will be appended to the prompt.

Show child attributes

roleenum<string>required

The role of the message author.

Available options:systemuserassistanttool

contentoneOf

The content of the message. Can be a string for text-only messages, an array of content parts for multimodal messages, or null for assistant messages with tool_calls.

tool_callsobject[]

Tool calls generated by the model (assistant messages only).

Show child attributes

idstringrequired

ID of the tool call.

typeenum<string>required

The type of the tool call. Always 'function'.

Available options:function

functionobjectrequired

The function that the model called.

Show child attributes

namestringrequired

The name of the function to call.

argumentsstringrequired

The arguments to call the function with, as a JSON string.

tool_call_idstring

Tool call ID this message is responding to (tool role only).

streambooleandefault: false

If true, partial message deltas will be sent as server-sent events.

temperaturenumberdefault: 1

Sampling temperature between 0 and 2. Higher values make output more random.

top_pnumber

Nucleus sampling parameter. Must be greater than 0.

max_tokensinteger

Maximum number of tokens to generate.

max_completion_tokensinteger

Maximum number of completion tokens to generate.

presence_penaltynumberdefault: 0

Penalizes tokens based on presence in the text.

frequency_penaltynumberdefault: 0

Penalizes tokens based on frequency in the text.

seedinteger

Random seed for generation.

stopstring[]

Up to 4 sequences where the API will stop generating.

logit_biasobject[]

Modifies the likelihood of specified tokens appearing in the completion.

Show child attributes

token_idstringrequired

Token ID to apply bias to.

bias_valueintegerrequired

Bias value to apply to the token.

reasoning_effortenum<string>

Controls the amount of reasoning effort the model uses. Note: This parameter is provider/model-specific and may not be supported by all models (e.g., OpenAI models do not support this parameter). This will be overridden if extra_body.reasoning is specified.

Available options:nonelowminimalmediumhighxhigh

userstring

A unique identifier for the end user. When used with a router, the same user will consistently receive the same variant across requests (sticky routing).

web_searchobject

Tool-based web search configuration. The LLM calls a search engine in a tool-calling loop, then synthesizes a grounded answer with url_citation annotations. Works with any LLM that supports tool calling. Mutually exclusive with web_search_options. See Web Search for details.

Show child attributes

engineenum<string>default: "exa"

Search backend. Valid values are exa and google.

Available options:exagoogle

max_resultsintegerdefault: 3

Search results per search call.

max_stepsintegerdefault: 1

Maximum search/refine rounds.

web_search_optionsobject

Native web search using the provider's built-in search grounding (no tool loop). Supported by OpenAI (search models only), Anthropic, Google / Vertex AI, and Groq. Mutually exclusive with web_search. See Web Search for details.

Show child attributes

search_context_sizeenum<string>default: "medium"

How much web context to retrieve.

Available options:lowmediumhigh

user_locationobject

Approximate user location for search relevance.

Show child attributes

typeenum<string>

Available options:approximate

countrystring

citystring

modalitiesenum<string>[]default: ["text"]

Output modalities to generate. Defaults to ["text"]. Include "image" to request image generation (e.g., ["text", "image"]). Currently supported for OpenAI and Google image models.

image_configobject

Configuration for image output. Optional when requesting image output via modalities: ["image"].

Show child attributes

aspect_ratiostring

Aspect ratio for the generated image (e.g., 1:1, 16:9, 9:16). Supported by Google models only.

image_sizestring

Size of the generated image.

Google: model-specific sizes such as 1K or 2K.
OpenAI: pixel dimensions as WxH (e.g., 1024x1024).

partial_imagesinteger

Number of partial/progressive image previews during streaming. Only used with stream: true. Defaults to 1 if unset. Supported by OpenAI models only.

ninteger

Number of images to generate.

Google: Only support 1.
OpenAI: Support 1-10.

extra_bodyobject

Optional parameters for model routing and optimization.

Show child attributes

modelsstring[]

List of model identifiers for fallbacks or auto selection pool.

ignorestring[]

Providers or models to exclude.

sortstring[]

The sorting strategy to use for this request. Available sorting strategies: price, latency, throughput, intelligence, math, coding.

reasoningobject

Reasoning configuration. If specified, this will override the reasoning_effort parameter in the request body. Note: This parameter is provider/model-specific and may not be supported by all models. Unsupported parameters may return errors or be silently ignored depending on the provider.

Show child attributes

effortenum<string>

Controls the reasoning effort level. The server will default to MEDIUM if effort is not specified. NONE disables reasoning entirely. MINIMAL uses ~10% of max completion tokens, LOW ~20%, MEDIUM ~50%, HIGH ~80%, XHIGH ~95%.

Available options:unspecifiednoneminimallowmediumhighxhigh

max_tokensinteger

Maximum number of tokens to use for reasoning. Anthropic/Google-style control. Takes precedence over effort when specified. For providers that only support effort levels, this is converted to the appropriate level.

excludeboolean

Whether to exclude reasoning tokens from the response. When true, the model still uses reasoning internally but doesn't return it. Default is false (reasoning is included in response if available).

providerobject

Provider routing configuration. Use when model is specified without a provider prefix (e.g., gpt-oss-120b) to control which providers are tried and in what order.

Show child attributes

orderstring[]

Explicit list of providers to try, in order. Example: ["groq", "fireworks"]. When specified, providers are tried in this exact order (sort criteria will be ignored).

allow_fallbacksbooleandefault: true

Whether to allow falling back to the next provider if the current one fails. Defaults to true.

prompt_variablesobject

Variables for substitution in prompt templates. Example: {"name": "John", "topic": "AI"}. These variables will only be substituted in prompts specified in a router, not in messages sent with each request.

web_searchobject

For OpenAI SDK compatibility, pass web_search via extra_body (equivalent to setting it at the top level). Tool-based web search configuration. Mutually exclusive with web_search_options. See Web Search for details.

Show child attributes

engineenum<string>default: "exa"

Search backend. Valid values are exa and google.

Available options:exagoogle

max_resultsintegerdefault: 3

Search results per search call.

max_stepsintegerdefault: 1

Maximum search/refine rounds.

web_search_optionsobject

For OpenAI SDK compatibility, pass web_search_options via extra_body (equivalent to setting it at the top level). Native web search grounding. Mutually exclusive with web_search. See Web Search for details.

Show child attributes

search_context_sizeenum<string>default: "medium"

How much web context to retrieve.

Available options:lowmediumhigh

user_locationobject

Approximate user location for search relevance.

Show child attributes

typeenum<string>

Available options:approximate

countrystring

citystring

audioobject

Convert the generated text to Inworld TTS audio. Supports streaming and non-streaming requests. See LLM + TTS.

Show child attributes

voicestringrequired

Voice ID for speech synthesis.

modelstringrequired

Inworld TTS model ID; must start with inworld-. Independent of the top-level LLM model.

timestamp_typeenum<string>

Opt into timing entries for words or characters. Values are lowercase. Omit to disable timestamps. Alignment can add latency.

Available options:wordcharacter

Response

200 - application/json

idstring

Unique identifier for the chat completion.

objectstring

Object type, always 'chat.completion'.

createdinteger

Unix timestamp when the completion was created.

modelstring

The model that was actually used.

choicesobject[]

List of chat completion choices.

Show child attributes

indexinteger

messageobject

Show child attributes

rolestring

Always 'assistant' for responses.

contentstring

The generated content. Null when tool_calls is present. Empty when Inworld TTS audio is returned; read audio.transcript for the spoken text.

tool_callsobject[]

Tool calls generated by the model (when using tools).

Show child attributes

idstring

typestring

functionobject

Show child attributes

namestring

argumentsstring

audioobject

Synthesized Inworld TTS audio in a non-streaming completion. The message content is empty; the spoken text is in transcript.

Show child attributes

idstring

Identifier for the generated audio.

datastring

Base64-encoded PCM16 little-endian mono audio, at 48,000 Hz by default.

transcriptstring

The synthesized text.

timestampsobject[]

Timing entries when audio.timestamp_type was requested and alignment is available. Times refer to the complete response audio.

Show child attributes

tokenstringrequired

Word or character associated with this timing entry.

start_timenumberrequired

Start time in seconds from the beginning of the complete response audio, including preceding sentences.

end_timenumberrequired

End time in seconds from the beginning of the complete response audio, including preceding sentences.

finish_reasonstring

Reason for stopping: stop, length, or tool_call.

usageobject

Token usage statistics.

Show child attributes

prompt_tokensinteger

Tokens in the prompt.

completion_tokensinteger

Tokens in the completion.

total_tokensinteger

Total tokens used.

metadataobject

Routing metadata providing transparency into model selection decisions.

Show child attributes

attemptsobject[]

List of model attempts, including both successful and failed attempts.

Show child attributes

modelstring

The model identifier that was attempted.

successboolean

Whether this attempt succeeded.

time_to_first_token_msinteger

Time to receive the first token in milliseconds.

generation_idstring

Unique identifier for tracing this request in the Inworld Portal.

reasoningstring

Human-readable explanation of why a model was selected based on the routing strategy.

total_duration_msinteger

Total request duration in milliseconds.

Create chat completion

curl --request POST \
  --url https://api.inworld.ai/v1/chat/completions \
  --header 'Authorization: <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "auto",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "extra_body": {
    "models": [
      "openai/gpt-4o-mini",
      "google-ai-studio/gemini-2.0-flash"
    ],
    "sort": [
      "price"
    ]
  }
}'

{
  "id": "chatcmpl-1772347141924",
  "object": "chat.completion",
  "created": 1772347141,
  "model": "openai/gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 9,
    "total_tokens": 18
  },
  "metadata": {
    "attempts": [
      {
        "model": "openai/gpt-4o",
        "success": true,
        "time_to_first_token_ms": 428
      }
    ],
    "generation_id": "9b365b38-f09f-96d1-8c77-99b28c8b74bf",
    "reasoning": "Using specified model: 'openai/gpt-4o' - success",
    "total_duration_ms": 472
  }
}