--- 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' | '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' | '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' | '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' | '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 - `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 - `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 --- [API](https://skmtc.net/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.net/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openrouterteam/openrouter-api/revisions/b0e4c71ef36a/schema)