Chat Completions

Create chat completion

Generate a response for the given chat conversation

POST/v1/chat/completions

Call 100+ models from different providers through one API. Set model to auto to choose a model automatically based on criteria such as price, latency, or performance.

For conditional routing, A/B testing across variants, or reusable configurations, create a router. Set the model field to inworld/<router-id>, for example inworld/my-router.

To use web search in an answer, set web_search at the top level of the request or, with the OpenAI SDK, in extra_body.

To generate and save images, see Image generation, including reference images and model-specific output settings.

For voice output, see Voice responses, 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., deepseek-v4-flash). 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.4). 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).

compressionobject

Prompt compression for this message only. Ignored when the request or the router variant sets compression, which applies to every compressible message instead. Tool-result messages are never compressed. See Prompt compression.

Show child attributes

aggressivenessnumberdefault: 0.5

How strongly to compress this message. Higher values save more tokens but may reduce fidelity. 0 disables compression.

streambooleandefault: false

If true, partial message deltas will be sent as server-sent events. For image output, Google AI Studio and OpenAI support streaming; Google Vertex requires false. Read image output from choices[].delta.images. See Image generation.

stream_optionsobject

Streaming options. Usage is streamed whenever the provider reports it, with or without this field. include_usage: true only changes the shape of the usage chunk: its choices array is empty, as in OpenAI's API. Without it, that chunk has one choice with an empty delta. See Streaming.

Show child attributes

include_usageboolean

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.

stoponeOf

A sequence, or a list of sequences, where the model stops generating.

logit_biasobject

Map of token id (as a string) to a bias from -100 to 100, as in OpenAI's API. Values outside that range are clamped.

toolsobject[]

Tools the model may call, in OpenAI's format ({"type": "function", "function": {...}}). function.strict is sent only to models whose provider enforces it; other models do not receive it. See Tool calling.

parallel_tool_callsboolean

Set to false to ask for at most one tool call per turn. Sent to the provider only when the request has tools. OpenAI and Anthropic models honor it; Google models ignore it.

tool_choiceoneOf

auto, none, required, a named tool ({"type": "function", "function": {"name": "..."}}) or an allowed_tools object, as in OpenAI's API. any is read as required. Any other value returns 400. Some models cannot be forced to call a tool; see Tool calling.

response_formatobject

Structured output: {"type": "json_object"} or {"type": "json_schema", "json_schema": {...}}, as in OpenAI's API.

ninteger

Not supported. Only one choice is returned; the parameter is ignored.

logprobsboolean

Not supported. The parameter is ignored.

top_logprobsinteger

Not supported. The parameter is ignored, like logprobs. It is still validated: without logprobs: true, or outside 0 to 20, the request returns 400.

top_kinteger

Sample from the k most likely tokens, for models that support it.

min_pnumber

Minimum token probability relative to the most likely token, for models that support it.

repetition_penaltynumber

Penalty for repeated tokens, for models that support it.

prompt_cache_keystring

OpenAI's prompt cache key. What it does depends on the model generation: on earlier OpenAI models it helps route requests that share a prefix to the same cache, and on newer ones it keeps cache accounting separate, for example per customer; see OpenAI's prompt caching guide. Passed to OpenAI and Azure OpenAI models only; other providers do not receive it. See Prompt caching.

prompt_cache_retentionstring

OpenAI's prompt cache retention policy, such as in_memory or 24h. Passed to OpenAI and Azure OpenAI models only. Accepted values depend on the model; see OpenAI's prompt caching guide.

compressionobject

Prompt compression for this request. Compresses every compressible message and overrides a router variant's setting; {"aggressiveness": 0} turns compression off. Can also be sent in extra_body. See Prompt compression.

Show child attributes

aggressivenessnumberdefault: 0.5

How strongly to compress. Higher values save more tokens but may reduce fidelity. 0 disables compression.

sessionstring

An optional session id for grouping the requests of one conversation. Printable ASCII, up to 128 characters; default is reserved. Can also be sent in extra_body.

metadataobject

Request metadata, available to a saved router's conditional routing expressions and prompt templates. Can also be sent in extra_body.

reasoning_effortenum<string>

How much reasoning the model does, for models that support it. Case-insensitive. An unrecognized value is ignored, and for a model that does not support reasoning effort the parameter is dropped with a warning in metadata.attempts[].warnings. Takes precedence over extra_body.reasoning.effort.

Available options:noneminimallowmediumhighxhighmax

userstring

A stable id for your end user. When model is a saved router, it keeps a user on the same traffic-splitting variant; without it, the variant is chosen at random per request. It is not forwarded to the provider.

web_searchobject

Web search configuration, at the top level or in extra_body. With a router-run engine (exa, brave or google), the LLM calls a search engine in a tool-calling loop, then synthesizes a grounded answer with url_citation annotations; this works with any LLM that supports tool calling. With engine: "native", the provider's built-in search is used. Mutually exclusive with web_search_options. See Web search for details.

Show child attributes

engineenum<string>default: "exa"

Search backend: exa, brave or google, or native for the provider's built-in search.

Available options:exabravegooglenative

max_resultsintegerdefault: 3

Search results per search call, 1 to 10.

max_stepsintegerdefault: 1

Maximum search rounds before the final answer, 1 to 5.

web_search_optionsobject

Native web search using the provider's built-in search grounding (no tool loop). Supported by OpenAI, Azure 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>

How much web context to retrieve. Defaults to medium. Used by OpenAI and Azure OpenAI; on Anthropic it sets how many searches the model can run; Google and Groq ignore it.

Available options:lowmediumhigh

modalitiesenum<string>[]

Output modalities to generate. Include "image" to request image generation (e.g., ["text", "image"]); ["image"] alone also works. Supported by models whose spec.outputModalities in the List models API includes image (filter with ?output_modalities=image). When omitted, a model that generates images uses its catalog output modalities, so it still returns images; other models return text.

image_configobject

Configuration for image output. Optional; applies when modalities includes "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, when the request has no reference image. Inworld ignores it, without an error, for other providers and when the request includes a reference image.

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, from 0 to 3. Only used with stream: true. When unset, OpenAI sends no previews, only the final image. Supported by OpenAI models only. Inworld passes the value to the provider as sent; OpenAI rejects a value outside 0 to 3, and other providers ignore the field.

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[]

Model ids for fallbacks, or the candidate pool for auto. Fallbacks are tried in the order listed unless sort is set. A bare provider name (for example openai) stands for all of that provider's models. auto is not allowed here: at the top level it returns 400, and inside extra_body it matches no model.

ignorestring[]

Providers or models to exclude from selection. A provider/model named in model is never excluded; for a bare model id, ignore can exclude its providers. auto is not allowed here: at the top level it returns 400, and inside extra_body it matches no model.

sortstring[]

The sorting strategy for auto selection, fallbacks, and the providers of a model named without a provider prefix: price, latency, throughput, intelligence, math, coding. Add _asc or _desc to set the direction (for example latency_desc). In a request, sort is an array of strings; a saved router's model_selection.sort uses SortCriteria objects instead.

reasoningobject

Reasoning configuration. effort applies only when the top-level reasoning_effort is not set.

Show child attributes

effortenum<string>

Available options:noneminimallowmediumhighxhighmax

max_tokensinteger

Reasoning token budget, for models that take one.

excludeboolean

Leave the reasoning text out of the response.

providerobject

Provider routing configuration. Works on any request; no router is needed. Use when model is specified without a provider prefix (e.g., deepseek-v4-flash) to control which providers are tried and in what order. Ignored when model has a provider prefix or is auto. See Provider routing.

Show child attributes

orderstring[]

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

allow_fallbacksbooleandefault: true

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

prompt_variablesobject

Variables for the prompt templates of a saved router (not for messages sent with each request). Values can be any JSON type. They are also available to conditional routing expressions, where metadata wins on a name clash. See prompt variables.

web_searchobject

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

Show child attributes

engineenum<string>default: "exa"

Search backend: exa, brave or google, or native for the provider's built-in search.

Available options:exabravegooglenative

max_resultsintegerdefault: 3

Search results per search call, 1 to 10.

max_stepsintegerdefault: 1

Maximum search rounds before the final answer, 1 to 5.

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>

How much web context to retrieve. Defaults to medium. Used by OpenAI and Azure OpenAI; on Anthropic it sets how many searches the model can run; Google and Groq ignore it.

Available options:lowmediumhigh

fallbackobject

Fall back to the next model when the first token is slow.

Show child attributes

ttft_timeoutstringrequired

A duration of at least 300ms, for example "800ms" or "1.5s".

sessionstring

Same as the top-level session.

metadataobject

Same as the top-level metadata.

compressionobject

Prompt compression for this request. See prompt compression.

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.

formatenum<string>default: "pcm16"

Encoding of the returned audio: pcm16 (16-bit signed little-endian PCM), mulaw (G.711 µ-law) or alaw (G.711 A-law). All are mono and headerless. Any other value returns 400.

Available options:pcm16mulawalaw

sample_rateinteger

Output sample rate in Hz. pcm16 accepts 8000, 16000, 22050, 24000, 32000, 44100 or 48000 (default 48000); mulaw and alaw accept 8000 only, the default. Any other value returns 400.

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 text. Can be empty when the model returns image output without accompanying text, only tool calls, or Inworld TTS audio (read audio.transcript for the spoken text).

imagesobject[]

Generated images, when image output is requested. An image may be returned without text in content. See Image generation for saving images.

Show child attributes

typeenum<string>

Available options:image_url

image_urlobject

Show child attributes

urlstring

A base64 image data URL, such as data:image/png;base64,..., or a download URL.

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 mono, headerless audio in the requested audio.format, at the requested audio.sample_rate. Defaults: pcm16 (16-bit little-endian) at 48,000 Hz; mulaw and alaw are always 8,000 Hz.

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.

reasoningstring

The model's reasoning text, for reasoning models that return it.

annotationsobject[]

Citations, for example url_citation entries from web search.

finish_reasonenum<string>

Why the model stopped.

Available options:stoplengthtool_callscontent_filter

usageobject

Token usage statistics.

Show child attributes

prompt_tokensinteger

Tokens in the prompt.

completion_tokensinteger

Tokens in the completion.

total_tokensinteger

Total tokens used.

prompt_tokens_detailsobject

Always includes cached_tokens (prompt tokens read from cache). cache_write_tokens, audio_tokens, image_tokens and text_tokens appear when nonzero.

Show child attributes

cached_tokensinteger

Prompt tokens read from the cache. 0 when nothing was read. See Prompt caching.

cache_write_tokensinteger

Prompt tokens written to a new cache entry. On Google models with explicit caching, the request that writes the cache also reads it, so cached_tokens reports the same tokens.

completion_tokens_detailsobject

reasoning_tokens, audio_tokens, image_tokens and text_tokens appear when nonzero. For image output, image_tokens counts the tokens of the generated images.

Show child attributes

reasoning_tokensinteger

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 provider/model identifier that was attempted, for example openai/gpt-5.2. The prefix is the provider.

successboolean

Whether this attempt succeeded.

time_to_first_token_msinteger

Time to receive the first token in milliseconds.

status_codeinteger

HTTP status of a failed attempt.

errorstring

Why the attempt failed.

duration_msnumber

Duration of the attempt in milliseconds.

warningsstring[]

Notes about the attempt, for example parameters skipped because the model does not support them.

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. Not included on streamed responses, where metadata arrives on the first chunk.

route_idstring

The saved router's route that was chosen, when model is a saved router.

variant_idstring

The saved router's variant that was chosen, when model is a saved router.

compression_warningsstring[]

Warnings from prompt compression, when it ran. Non-streaming responses only.

compressionobject

Stats from prompt compression, present when at least one message was compressed. Non-streaming responses only.

Show child attributes

original_tokensinteger

compressed_tokensinteger

saved_tokensinteger

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.5-flash-lite"
    ],
    "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
  }
}