---
title: "Create chat completion"
method: POST
path: "/v1/chat/completions"
tags: ["Chat Completions"]
---

# Create chat completion

`POST /v1/chat/completions`

## Request body

- ChatCompletionRequest
  - `model` string, required — The model to use, which can be: - A model id (e.g., `gpt-oss-120b`). The best provider is [automatically selected](/router/usage/specific-model#provider-routing) by latency, or you can control provider selection via `extra_body.provider`. See [Models](/api-reference/modelsAPI/modelservice/list-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/`.
  - `messages` Message[], 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.
    - `role` 'system' | 'user' | 'assistant' | 'tool', required — The role of the message author.
    - `content` union — 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.
      - string — Text-only message content.
      - ContentPart[] — An array of content parts for a multimodal message.
        - union — A single content part in a multimodal message. Discriminated by `type`.
          - TextContentPart — A text content part.
            - `type` 'text', required
            - `text` string, required — The text content.
          - ImageContentPart — An image content part.
            - `type` 'image_url', required
            - `image_url` ImageUrl, required — Image URL or base64 data URI with optional detail level.
              - …
          - InputAudioContentPart — An audio content part.
            - `type` 'input_audio', required
            - `input_audio` InputAudio, required — Base64-encoded audio input.
              - …
    - `tool_calls` ToolCall[] — Tool calls generated by the model (assistant messages only).
      - `id` string, required — ID of the tool call.
      - `type` 'function', required — The type of the tool call. Always 'function'.
      - `function` object, required — The function that the model called.
        - `name` string, required — The name of the function to call.
        - `arguments` string, required — The arguments to call the function with, as a JSON string.
    - `tool_call_id` string — Tool call ID this message is responding to (tool role only).
  - `stream` boolean — If true, partial message deltas will be sent as server-sent events.
  - `temperature` number — Sampling temperature between 0 and 2. Higher values make output more random.
  - `top_p` number — Nucleus sampling parameter. Must be greater than 0.
  - `max_tokens` integer — Maximum number of tokens to generate.
  - `max_completion_tokens` integer — Maximum number of completion tokens to generate.
  - `presence_penalty` number — Penalizes tokens based on presence in the text.
  - `frequency_penalty` number — Penalizes tokens based on frequency in the text.
  - `seed` integer — Random seed for generation.
  - `stop` string[] — Up to 4 sequences where the API will stop generating.
  - `logit_bias` LogitBias[] — Modifies the likelihood of specified tokens appearing in the completion.
    - `token_id` string, required — Token ID to apply bias to.
    - `bias_value` integer, required — Bias value to apply to the token.
  - `reasoning_effort` 'none' | 'low' | 'minimal' | 'medium' | 'high' | 'xhigh' — 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.
  - `user` string — 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_search` WebSearchConfig — Web search configuration (under `extra_body`). The LLM calls a search engine in a tool-calling loop, then synthesizes a grounded answer. See [Web search](/router/capabilities/web-search).
    - `engine` 'exa' | 'google' — Search backend. Valid values are `exa` and `google`.
    - `max_results` integer — Search results per search call.
    - `max_steps` integer — Maximum search/refine rounds.
  - `web_search_options` WebSearchOptions — OpenAI-compatible web search options on the request body. Passed through to providers that support native web search. See [Web search](/router/capabilities/web-search).
    - `search_context_size` 'low' | 'medium' | 'high' — How much web context to retrieve.
    - `user_location` object — Approximate user location for search relevance.
      - `type` 'approximate'
      - `country` string
      - `city` string
  - `modalities` string[] — 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_config` ImageConfig — Configuration for image output in chat completions. Optional when requesting image output via `modalities: ["image"]`.
    - `aspect_ratio` string — Aspect ratio for the generated image (e.g., `1:1`, `16:9`, `9:16`). Supported by Google models only.
    - `image_size` string — Size of the generated image. - Google: model-specific sizes such as `1K` or `2K`. - OpenAI: pixel dimensions as WxH (e.g., `1024x1024`).
    - `partial_images` integer — Number of partial/progressive image previews during streaming. Only used with `stream: true`. Defaults to 1 if unset. Supported by OpenAI models only.
    - `n` integer — Number of images to generate. - Google: Only support 1. - OpenAI: Support 1-10.
  - `extra_body` ExtraBody — Optional parameters for model routing and optimization.
    - `models` string[] — List of model identifiers for fallbacks or auto selection pool.
    - `ignore` string[] — Providers or models to exclude.
    - `sort` string[] — The sorting strategy to use for this request. Available sorting strategies: `price`, `latency`, `throughput`, `intelligence`, `math`, `coding`.
    - `reasoning` ReasoningConfig — Reasoning configuration for models that support chain-of-thought reasoning. Provides a unified interface across different providers (OpenAI, Anthropic, Google, Groq, etc.).
      - `effort` 'unspecified' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' — 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%.
      - `max_tokens` integer — 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.
      - `exclude` boolean — 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).
    - `provider` ProviderConfig — Configuration for provider-level routing when using a model without a provider prefix.
      - `order` string[] — 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_fallbacks` boolean — Whether to allow falling back to the next provider if the current one fails. Defaults to true.
    - `prompt_variables` object — Variables for substitution in prompt templates. Example: {"name": "John", "topic": "AI"}. These variables will only be substituted in prompts specified in a [router](/api-reference/routerAPI/routerservice/create-router), not in messages sent with each request.
    - `web_search` WebSearchConfig — Web search configuration (under `extra_body`). The LLM calls a search engine in a tool-calling loop, then synthesizes a grounded answer. See [Web search](/router/capabilities/web-search).
      - `engine` 'exa' | 'google' — Search backend. Valid values are `exa` and `google`.
      - `max_results` integer — Search results per search call.
      - `max_steps` integer — Maximum search/refine rounds.
    - `web_search_options` WebSearchOptions — OpenAI-compatible web search options on the request body. Passed through to providers that support native web search. See [Web search](/router/capabilities/web-search).
      - `search_context_size` 'low' | 'medium' | 'high' — How much web context to retrieve.
      - `user_location` object — Approximate user location for search relevance.
        - `type` 'approximate'
        - `country` string
        - `city` string

## Response `200`

A successful response. Returns either a complete chat completion or streaming chunks.

- ChatCompletionResponse
  - `id` string — Unique identifier for the chat completion.
  - `object` string — Object type, always 'chat.completion'.
  - `created` integer — Unix timestamp when the completion was created.
  - `model` string — The model that was actually used.
  - `choices` Choice[] — List of chat completion choices.
    - `index` integer
    - `message` object
      - `role` string — Always 'assistant' for responses.
      - `content` string, nullable — The generated content. Null when tool_calls is present.
      - `tool_calls` object[] — Tool calls generated by the model (when using tools).
        - `id` string
        - `type` string
        - `function` object
          - `name` string
          - `arguments` string
    - `finish_reason` string — Reason for stopping: stop, length, or tool_call.
  - `usage` object — Token usage statistics.
    - `prompt_tokens` integer — Tokens in the prompt.
    - `completion_tokens` integer — Tokens in the completion.
    - `total_tokens` integer — Total tokens used.
  - `metadata` Metadata — Routing metadata providing transparency into model selection decisions.
    - `attempts` Attempt[] — List of model attempts, including both successful and failed attempts.
      - `model` string — The model identifier that was attempted.
      - `success` boolean — Whether this attempt succeeded.
      - `time_to_first_token_ms` integer — Time to receive the first token in milliseconds.
    - `generation_id` string — Unique identifier for tracing this request in the Inworld Portal.
    - `reasoning` string — Human-readable explanation of why a model was selected based on the routing strategy.
    - `total_duration_ms` integer — Total request duration in milliseconds.

## Other responses

- `400` — Bad request
- `401` — Unauthorized - Invalid or missing API key

---

[API](https://skmtc.net/inworld/apis/inworld-text-to-speech-api.md) · [All operations](https://skmtc.net/inworld/apis/inworld-text-to-speech-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/inworld/inworld-text-to-speech-api/revisions/e79009799a0d/schema)