Chat Completions
Create chat completion
Generate a response for the given chat conversation
/v1/chat/completionsCall 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.
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 viaextra_body.provider. See Models for available models. - A provider-prefixed model id (e.g.,
openai/gpt-5.4): the List models entry'sprovider,/, then itsmodel. This specifies the provider and model to use. When the model name itself contains a/, keep the provider in front (e.g.,groq/openai/gpt-oss-120b): the router reads the part before the first/as the provider when it names one, soopenai/gpt-oss-120basks the provideropenaifor it. - A model hosted by Inworld, as
inworld/models/<name>(e.g.,inworld/models/deepseek-v4-flash). autofor automatic model selection based on criteria like price, latency, or intelligence- A router, which is specified by
inworld/<router-name>. The routernamemust be prefixed byinworld/.
See Model ids.
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
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 calls generated by the model (assistant messages only).
Show child attributes
Marks this whole message as the end of a block to cache, on models with explicit caching, when content is a string. For multipart content, put cache_control on a content part. See Prompt caching.
Show child attributes
Cache lifetime, such as 5m or 1h. Accepted values depend on the model; some accept only 5m and 1h. Without it, the provider's default applies.
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.
If true, partial message deltas will be sent as server-sent events. While the model sends nothing, the stream carries keepalive chunks with an empty delta; skip them. See Streaming. Image output can stream too; a model that can't stream image output fails with 400. Read image output from choices[].delta.images. See Image generation.
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.
Sampling temperature between 0 and 2. Higher values make output more random.
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.
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.
Set to false to ask for at most one tool call per turn. Sent to the provider only when the request has tools. Some models ignore it.
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.
Structured output: {"type": "json_object"} or {"type": "json_schema", "json_schema": {...}}, as in OpenAI's API. Anthropic models have no JSON mode: they drop json_object, without an error, and answer in ordinary text. Use json_schema with a schema there. See Structured outputs.
Not supported. Only one choice is returned; the parameter is ignored. For image output, set the number of images with image_config.n.
Not supported. The parameter is ignored, like logprobs. It is still validated: without logprobs: true, or outside 0 to 20, the request returns 400.
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 only to models that take it; other models do not receive it, without an error. See Prompt caching.
OpenAI's prompt cache retention policy, such as in_memory or 24h. Passed only to models that take it; other models do not receive it, without an error. Accepted values depend on the model; see OpenAI's prompt caching guide.
Some models only: one request-wide cache breakpoint. The provider puts it on the last cacheable block and moves it forward as the conversation grows. Other models ignore it. To mark a block yourself, put cache_control on a text content part, on a message whose content is a string, or on a tools entry instead. See Prompt caching.
Prompt compression for this request. Compresses every compressible message and overrides a router variant's setting; {"aggressiveness": 0} turns compression off. Compression is not billed; usage.prompt_tokens counts the compressed prompt. It currently drops cache_control on the parts it rewrites. Can also be sent in extra_body. See Prompt compression.
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.
Request metadata, available to a saved router's conditional routing expressions and prompt templates. Can also be sent in extra_body.
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
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 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.
Native web search using the provider's built-in search grounding (no tool loop). Works on some models. spec.capabilities.webSearch: true in List models confirms it, but false doesn't rule it out: some models report false and still search. On a model without native search, that attempt fails with 400. Mutually exclusive with web_search. See Web Search for details.
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. When set without "image", an image model returns no images. With an Inworld TTS audio object (voice responses), ["text", "audio"], the shape the OpenAI SDK sends for spoken output, is accepted: the model writes text and Inworld TTS speaks it. Leaving modalities out works the same.
Configuration for image output. Optional; applies when modalities includes "image", or when modalities is omitted and the model generates images.
Show child attributes
Aspect ratio for the generated image (e.g., 1:1, 16:9, 9:16). Used by some models, when the request has no reference image. Inworld ignores it, without an error, on other models and when the request includes a reference image.
Size of the generated image. Accepted values depend on the model: some take a size tier, such as 1K or 2K, and others take pixel dimensions as WxH (e.g., 1024x1024).
Rendering quality of the generated image, on the models that take it, such as low, medium, high or auto; lower quality returns fewer image tokens (usage.completion_tokens_details.image_tokens), which are billed as output tokens. Applies to generation and to requests with a reference image. Inworld passes the value as sent, and a model that takes quality rejects a value it does not accept with 400. When unset, the model uses its default. Other models never receive the field: Inworld ignores it without an error, whatever its value.
Number of partial/progressive image previews during streaming, from 0 to 3. Only used with stream: true. When unset, the model sends no previews, only the final image. Used by some models only. Inworld passes the value to the provider as sent; a model that sends previews rejects a value outside 0 to 3, and other models ignore the field.
Optional parameters for model routing and optimization.
Show child attributes
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. Write a model hosted by Inworld as inworld/<name> here, the form responses use. auto is not allowed here: at the top level it returns 400, and inside extra_body it matches no model.
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. Without models, and with any model but auto or a saved router, setting ignore also adds every other catalog model it doesn't exclude as a fallback, so it can reach other providers. With model: "inworld/<router-id>", the router replaces the request's models, ignore, sort and provider with the selected variant's settings, so request-level ignore has no effect. See Use only one provider. auto is not allowed here: at the top level it returns 400, and inside extra_body it matches no model.
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.
Reasoning configuration. effort applies only when the top-level reasoning_effort is not set.
Show child attributes
Leave the reasoning text out of the response. Only some models act on it; other models ignore it. See Reasoning.
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
Explicit list of providers to try, in order. Example: ["deepseek", "inworld"]. When specified, providers are tried in this exact order (sort criteria will be ignored), and providers not in the list are not used.
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 templates.
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.
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.
Fall back to the next model when the first token is slow.
Prompt compression for this request. See prompt compression.
Speak the generated answer with Inworld TTS (a voice response), streaming or not. Can't be combined with response_format json_schema or json_object; with stream: true, also not with n greater than 1, logprobs: true, or a router-run web_search engine (exa, brave, google). Those combinations return 400. If synthesis fails, the request returns 502 upstream_error (or, once a stream has started, an error event) rather than a text-only answer. See Voice responses.
Show child attributes
Inworld TTS model ID; must start with inworld-. Any other value returns 400. 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
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.
Opt into timing entries for words or characters. Values are lowercase. Omit to disable timestamps. Alignment can add latency.
Available options:wordcharacter
How fast the voice speaks. 1.0 is the voice's normal pace; lower is slower. Values above 0.8 keep the best quality. A value outside 0.5 to 1.5 returns 400.
TTS sampling temperature; 0 means the default, 1.0. Higher values make the delivery more varied. Ignored by inworld-tts-2. Separate from the top-level temperature, which applies to the text model. A value outside 0 to 2 returns 400.
List of chat completion choices.
Show child attributes
Show child attributes
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).
Generated images, when image output is requested. Several images from image_config.n share this one array. An image may be returned without text in content. See Image generation for saving images.
Show child attributes
Tool calls generated by the model (when using tools).
Synthesized Inworld TTS audio in a non-streaming completion. The message content is empty; the spoken text is in transcript.
Show child attributes
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.
Timing entries when audio.timestamp_type was requested and alignment is available. Times refer to the complete response audio.
Show child attributes
Start time in seconds from the beginning of the complete response audio, including preceding sentences.
Citations, for example url_citation entries from web search.
Token usage statistics.
Show child attributes
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
Prompt tokens read from the cache, billed at the model's pricing.promptCacheReadToken. 0 when nothing was read. See Prompt caching.
Prompt tokens written to a new cache entry, billed at the model's pricing.promptCacheWriteToken. On Google models with explicit caching, the request that writes the cache also reads it, so cached_tokens reports the same tokens. Inworld bills nothing for how long a cache is kept.
Prompt tokens from audio input, when the provider reports them. Part of prompt_tokens.
Prompt tokens from image input, such as reference images for image generation, when the provider reports them. Part of prompt_tokens, billed at pricing.promptToken.
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. They are part of completion_tokens and billed at the model's output rate (pricing.completionToken in the List models API).
Show child attributes
Output tokens of generated audio, when the provider reports them. Part of completion_tokens.
Output tokens of generated images, when the provider reports them. Part of completion_tokens, billed at pricing.completionToken.
Routing metadata providing transparency into model selection decisions.
Show child attributes
List of model attempts, including both successful and failed attempts.
Show child attributes
The provider/model identifier that was attempted, for example openai/gpt-5.2. The prefix is the provider.
Human-readable explanation of why a model was selected based on the routing strategy.
Total request duration in milliseconds. Not included on streamed responses, where metadata arrives on the first chunk.
Warnings from prompt compression, when it ran. Non-streaming responses only.
Stats from prompt compression, present when at least one message was compressed. Non-streaming responses only.