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

# Create a chat completion

`POST /chat/completions`

Sends a request for a model response for the given chat conversation. Supports both streaming and non-streaming modes.

## Headers

- `X-OpenRouter-Metadata` 'disabled' | 'enabled' — Opt-in level for surfacing routing metadata on the response under `openrouter_metadata`.

## Request body

- ChatRequest — unresolved $ref

## Response `200`

Successful chat completion response

- ChatResult — Chat completion response
  - `choices` ChatChoice[], required — List of completion choices
    - `finish_reason` 'tool_calls' | 'stop' | 'length' | 'content_filter' | 'error' | 'null', nullable, required
    - `index` integer, required — Choice index
    - `logprobs` ChatTokenLogprobs, nullable — Log probabilities for the completion
      - `content` ChatTokenLogprob[], nullable, required — Log probabilities for content tokens
        - `bytes` integer[], nullable, required — UTF-8 bytes of the token
        - `logprob` number, double, required — Log probability of the token
        - `token` string, required — The token
        - `top_logprobs` object[], required — Top alternative tokens with probabilities
          - `bytes` integer[], nullable, required
          - `logprob` number, double, required
          - `token` string, required
      - `refusal` ChatTokenLogprob[], nullable — Log probabilities for refusal tokens
        - `bytes` integer[], nullable, required — UTF-8 bytes of the token
        - `logprob` number, double, required — Log probability of the token
        - `token` string, required — The token
        - `top_logprobs` object[], required — Top alternative tokens with probabilities
          - `bytes` integer[], nullable, required
          - `logprob` number, double, required
          - `token` string, required
    - `message` ChatAssistantMessage, required — Assistant message for requests and responses
      - `audio` ChatAudioOutput — Audio output data or reference
        - `data` string — Base64 encoded audio data
        - `expires_at` integer — Audio expiration timestamp
        - `id` string — Audio output identifier
        - `transcript` string — Audio transcript
      - `content` union — Assistant message content
        - string
        - ChatContentItems[]
          - union — Content part for chat completion messages
            - ChatContentText — Text content part
              - …
            - ChatContentImage — Image content part for vision models
              - …
            - ChatContentAudio — Audio input content part. Supported audio formats vary by provider.
              - …
            - LegacyChatContentVideo — Video input content part (legacy format - deprecated)
              - …
            - ChatContentVideo — Video input content part
              - …
            - ChatContentFile — File content part for document processing
              - …
      - `images` object[] — Generated images from image generation models
        - `image_url` object, required
          - `url` string, required — URL or base64-encoded data of the generated image
      - `model` string — Model that generated this assistant message
      - `name` string — Optional name for the assistant
      - `reasoning` string, nullable — Reasoning output
      - `reasoning_details` ReasoningDetailUnion[] — Reasoning details for extended thinking models
        - union — Reasoning detail union schema
          - ReasoningDetailSummary — Reasoning detail summary schema
            - `format` 'unknown' | 'openai-responses-v1' | 'azure-openai-responses-v1' | 'bedrock-openai-responses-v1' | 'bedrock-xai-responses-v1' | 'xai-responses-v1' | 'meta-responses-v1' | 'anthropic-claude-v1' | 'google-gemini-v1' | 'null', nullable
            - `id` string, nullable
            - `index` integer
            - `summary` string, required
            - `type` 'reasoning.summary', required
          - ReasoningDetailEncrypted — Reasoning detail encrypted schema
            - `data` string, required
            - `format` 'unknown' | 'openai-responses-v1' | 'azure-openai-responses-v1' | 'bedrock-openai-responses-v1' | 'bedrock-xai-responses-v1' | 'xai-responses-v1' | 'meta-responses-v1' | 'anthropic-claude-v1' | 'google-gemini-v1' | 'null', nullable
            - `id` string, nullable
            - `index` integer
            - `type` 'reasoning.encrypted', required
          - ReasoningDetailText — Reasoning detail text schema
            - `format` 'unknown' | 'openai-responses-v1' | 'azure-openai-responses-v1' | 'bedrock-openai-responses-v1' | 'bedrock-xai-responses-v1' | 'xai-responses-v1' | 'meta-responses-v1' | 'anthropic-claude-v1' | 'google-gemini-v1' | 'null', nullable
            - `id` string, nullable
            - `index` integer
            - `signature` string, nullable
            - `text` string, nullable
            - `type` 'reasoning.text', required
          - ReasoningDetailServerToolCall — Record of an OpenRouter server-tool invocation (e.g. openrouter:fusion), carried in reasoning_details so a prior tool call can be rehydrated into a later turn of the same conversation.
            - `arguments` string, required
            - `format` 'unknown' | 'openai-responses-v1' | 'azure-openai-responses-v1' | 'bedrock-openai-responses-v1' | 'bedrock-xai-responses-v1' | 'xai-responses-v1' | 'meta-responses-v1' | 'anthropic-claude-v1' | 'google-gemini-v1' | 'null', nullable
            - `id` string, nullable
            - `index` integer
            - `result` string, required
            - `tool_call_id` string, nullable
            - `tool_name` string, required
            - `type` 'reasoning.server_tool_call', required
      - `refusal` string, nullable — Refusal message if content was refused
      - `role` 'assistant', required
      - `tool_calls` ChatToolCall[] — Tool calls made by the assistant
        - `function` object, required
          - `arguments` string, required — Function arguments as JSON string
          - `name` string, required — Function name to call
        - `id` string, required — Tool call identifier
        - `type` 'function', required
  - `created` integer, required — Unix timestamp of creation
  - `id` string, required — Unique completion identifier
  - `model` string, required — Model used for completion
  - `object` 'chat.completion', required
  - `openrouter_metadata` OpenRouterMetadata
    - `attempt` integer, required
    - `attempts` RouterAttempt[]
      - `model` string, required
      - `provider` string, required
      - `status` integer, required
    - `endpoints` EndpointsMetadata, required
      - `available` EndpointInfo[], required
        - `model` string, required
        - `provider` string, required
        - `selected` boolean, required
      - `total` integer, required
    - `generation_time` integer — Milliseconds measured for the generation, from dispatching the upstream request until its response body ended. Divide the completion token count by this for throughput. Absent when no upstream request was dispatched.
    - `is_byok` boolean, required
    - `params` RouterParams
      - `quality_floor` number, double
      - `throughput_floor` number, double
      - `version_group` string
    - `pipeline` PipelineStage[]
      - `cost_usd` number, double, nullable
      - `data` object
      - `guardrail_id` string
      - `guardrail_scope` string
      - `name` string, required
      - `summary` string
      - `type` 'guardrail' | 'plugin' | 'server_tools' | 'response_healing' | 'context_compression', required — Categorical kind of a pipeline stage. Multiple plugins can share a type (e.g. all guardrail-level plugins emit `guardrail`); the `name` field disambiguates which plugin emitted it.
    - `region` string, nullable, required
    - `requested` string, required
    - `strategy` 'direct' | 'auto' | 'free' | 'latest' | 'alias' | 'fallback' | 'pareto' | 'bodybuilder' | 'fusion', required
    - `summary` string, required
  - `service_tier` string, nullable — The service tier used by the upstream provider for this request
  - `system_fingerprint` string, nullable, required — System fingerprint
  - `usage` ChatUsage — Token usage statistics
    - `completion_tokens` integer, required — Number of tokens in the completion
    - `completion_tokens_details` object, nullable — Detailed completion token usage
      - `accepted_prediction_tokens` integer, nullable — Accepted prediction tokens
      - `audio_tokens` integer, nullable — Tokens used for audio output
      - `reasoning_tokens` integer, nullable — Tokens used for reasoning
      - `rejected_prediction_tokens` integer, nullable — Rejected prediction tokens
    - `cost` number, double, nullable — Cost of the completion
    - `cost_details` CostDetails, nullable — Breakdown of upstream inference costs
      - `server_tool_cost` number, double, nullable — Metered server-tool execution cost (for example, shell sandbox time) billed for this request, in USD. Matches the billed checkpoint and settlement amounts exactly. 0 when a metered server tool ran but settled at zero dollars; absent when no metered server tool ran.
      - `upstream_inference_completions_cost` number, double, required
      - `upstream_inference_cost` number, double, nullable
      - `upstream_inference_prompt_cost` number, double, required
    - `is_byok` boolean — Whether a request was made using a Bring Your Own Key configuration
    - `prompt_tokens` integer, required — Number of tokens in the prompt
    - `prompt_tokens_details` object, nullable — Detailed prompt token usage
      - `audio_tokens` integer — Audio input tokens
      - `cache_write_tokens` integer — Tokens written to cache. Only returned for models with explicit caching and cache write pricing.
      - `cached_tokens` integer — Cached prompt tokens
      - `video_tokens` integer — Video input tokens
    - `server_tool_use_details` ServerToolUseDetails, nullable — Usage for server-side tool execution (e.g., web search)
      - `tool_calls_executed` integer, nullable — Number of OpenRouter server tool calls that executed and produced a result.
      - `tool_calls_requested` integer, nullable — Total number of OpenRouter server-orchestrated tool calls the model requested, across all tool types. Provider-native tools (e.g. native web search) are not counted here.
      - `web_search_requests` integer, nullable — Number of web searches performed by server-side tools. For server-orchestrated tool calls a web search is also counted in tool_calls_requested; provider-native web search may report web_search_requests only. Do not sum the two.
    - `total_tokens` integer, required — Total number of tokens

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed input
- `401` — Unauthorized - Authentication required or invalid credentials
- `402` — Payment Required - Insufficient credits or quota to complete request
- `403` — Forbidden - Authentication successful but insufficient permissions, or a guardrail blocked the request. When guardrails block and the `X-OpenRouter-Metadata: enabled` header is present, the response includes `openrouter_metadata` with full routing context and a `pipeline` array containing guardrail stage details.
- `404` — Not Found - Resource does not exist
- `408` — Request Timeout - Operation exceeded time limit
- `413` — Payload Too Large - Request payload exceeds size limits
- `422` — Unprocessable Entity - Semantic validation failure
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - Unexpected server error
- `502` — Bad Gateway - Provider/upstream API failure
- `503` — Service Unavailable - Service temporarily unavailable
- `524` — Infrastructure Timeout - Provider request timed out at edge network
- `529` — Provider Overloaded - Provider is temporarily overloaded

## Changes

- **2026-09-14** `54ab2e9ba857` — 3 info
  - added the new `AssemblyAI` enum value to the request property `provider/ignore/items/anyOf[#/components/schemas/ProviderName]/`
  - added the new `AssemblyAI` enum value to the request property `provider/only/items/anyOf[#/components/schemas/ProviderName]/`
  - added the new `AssemblyAI` enum value to the request property `provider/order/items/anyOf[#/components/schemas/ProviderName]/`
- **2026-09-09** `5d13b1d2e3ac` — 3 info
  - added the new `Near AI` enum value to the request property `provider/ignore/items/anyOf[#/components/schemas/ProviderName]/`
  - added the new `Near AI` enum value to the request property `provider/only/items/anyOf[#/components/schemas/ProviderName]/`
  - added the new `Near AI` enum value to the request property `provider/order/items/anyOf[#/components/schemas/ProviderName]/`
- **2026-09-08** `4c62b4e84b28` — 3 breaking
  - removed the enum value `NCompass` of the request property `provider/ignore/items/anyOf[#/components/schemas/ProviderName]/`
  - removed the enum value `NCompass` of the request property `provider/only/items/anyOf[#/components/schemas/ProviderName]/`
  - removed the enum value `NCompass` of the request property `provider/order/items/anyOf[#/components/schemas/ProviderName]/`
- **2026-09-08** `cfb1900ff6b4` — 1 warning
  - removed the request property `tools/items/anyOf[#/components/schemas/BashServerTool]/parameters/sleep_after_seconds`
- …earlier changes not shown

[Full history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/chat/completions/post.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/3e52cc4aca8e?raw)