Realtime TTS-2 is live. Built for realtime conversation that feels human. Read the Realtime TTS-2 announcement

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.

A standard API key can call chat completions, the Responses and Messages APIs, moderation and Decisions. To create, update or delete routers, the key also needs write permissions for the Router API. 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): the List models entry's provider, /, then its model. 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, so openai/gpt-oss-120b asks the provider openai for it.
  • A model hosted by Inworld, as inworld/models/<name> (e.g., inworld/models/deepseek-v4-flash).
  • 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/.

See Model ids.

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).

cache_controlobject

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

typeenum<string>

Available options:ephemeral

ttlstring

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.

cache_idstring

Some models only; other models ignore it. Keeps a separate cache for each value. Without it, a workspace has one explicit cache per model.

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. 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.

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. Some 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. 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.

ninteger

Not supported. Only one choice is returned; the parameter is ignored. For image output, set the number of images with image_config.n.

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 only to models that take it; other models do not receive it, without an error. See Prompt caching.

prompt_cache_retentionstring

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.

cache_controlobject

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.

Show child attributes

typeenum<string>

Available options:ephemeral

ttlstring

Cache lifetime: 5m (the default) or 1h.

compressionobject

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.

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_search_optionsobject

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.

Show child attributes

search_context_sizeenum<string>

How much web context to retrieve. Defaults to medium. How a model uses it differs: some models take it as the amount of search context, some as the number of searches they can run, and some 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. 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.

image_configobject

Configuration for image output. Optional; applies when modalities includes "image", or when modalities is omitted and the model generates images.

Show child attributes

aspect_ratiostring

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.

image_sizestring

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).

qualitystring

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.

partial_imagesinteger

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.

ninteger

Number of images to generate. In a non-streaming response, every image is in choices[0].message.images; Inworld returns one choice. Some models accept 1 to 10. Others return one image, and Inworld passes a larger value to them as sent, which they can reject.

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. 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.

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. 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.

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. Only some models act on it; other models ignore it. See Reasoning.

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: ["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.

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 templates.

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. How a model uses it differs: some models take it as the amount of search context, some as the number of searches they can run, and some 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

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

voicestringrequired

Voice ID for speech synthesis.

modelstringrequired

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

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

speaking_ratenumberdefault: 1

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.

temperaturenumber

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.

text_filtersstring[]

Strings to remove from the answer before it is spoken, matched literally (not as patterns), such as * or #. Up to 10 strings of up to 128 bytes each (UTF-8, so fewer characters for non-ASCII text); more, or a longer string, returns 400. Empty strings are ignored.

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. 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

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. The format is the one the model returns, usually PNG, and a data URL names it in its media type. No request field chooses the output format.

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, billed at the model's pricing.promptCacheReadToken. 0 when nothing was read. See Prompt caching.

cache_write_tokensinteger

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.

audio_tokensinteger

Prompt tokens from audio input, when the provider reports them. Part of prompt_tokens.

image_tokensinteger

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.

text_tokensinteger

Prompt tokens from text, when the provider reports them. Part of prompt_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. They are part of completion_tokens and billed at the model's output rate (pricing.completionToken in the List models API).

Show child attributes

reasoning_tokensinteger

Output tokens spent on reasoning. Part of completion_tokens.

audio_tokensinteger

Output tokens of generated audio, when the provider reports them. Part of completion_tokens.

image_tokensinteger

Output tokens of generated images, when the provider reports them. Part of completion_tokens, billed at pricing.completionToken.

text_tokensinteger

Output tokens of generated text, when the provider reports them. Part of completion_tokens.

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