Chat Completions
OpenAI-compatible chat endpoint for text, multimodal input, tools, and streaming when supported by the selected model.
https://onerouter.com/v1/chat/completionsTroubleshooting
Hitting an error? Every response carries an HTTP status and a JSON error body. See the Errors & Retries page for the full list of status codes and what to do about each.
Supported models
This endpoint works with every chat-capable model in the catalog — OpenAI, Anthropic, Google, DeepSeek, Qwen, and more. Browse the Text & Chat Models page or call GET /v1/models for the live list. Multimodal, tool, reasoning, and caching features depend on the selected model.
Overview
The Chat Completions endpoint is compatible with OpenAI's Chat Completions API. Send a list of messages representing the conversation, and the model returns the assistant's next message. It supports system instructions, multi-turn context, multimodal content parts, function/tool calling, structured outputs, and token-by-token streaming — exactly which features apply depends on the model you select.
You can call it with any OpenAI-compatible SDK by pointing the client's base URL at OneRouter, or with a plain HTTP request. The same request shape works across providers; only the model field changes.
Request headers
| Parameter | Type | Required | Description |
|---|---|---|---|
| Authorization | string · required | required | Bearer token authentication, formatted as `Bearer YOUR_API_KEY`. OpenAI-compatible clients use this header. |
| Content-Type | string · required | required | Must be `application/json` for chat requests. |
| x-api-key | string | optional | Alternative key header accepted for clients that send the API key directly. |
Request body
| Parameter | Type | Required | Description | Values |
|---|---|---|---|---|
| model | string | required | Model ID. Use `/v1/models` or the model list page to find available IDs. | |
| messages | array | required | Conversation so far. Each item has `role` and `content`. Content is a string, or an array of parts (`text`, `image_url`, `input_audio`) for multimodal models. | |
| temperature | number | optional | Sampling temperature, typically 0–2. Higher is more random. Tune either this or `top_p`. | |
| top_p | number | optional | Nucleus sampling, 0–1. Considers tokens in the top `p` probability mass. | |
| max_tokens | integer | optional | Maximum generated tokens. Newer OpenAI models use `max_completion_tokens`. | |
| stream | boolean | optional | Return SSE deltas instead of one complete JSON response. | truefalse |
| stream_options | object | optional | Streaming options. Set `{"include_usage": true}` to receive a final usage chunk. | |
| stop | string | array | optional | Up to 4 sequences where generation stops; the stop text is not returned. | |
| frequency_penalty | number | optional | −2 to 2. Positive values discourage repeating the same tokens. | |
| presence_penalty | number | optional | −2 to 2. Positive values encourage new topics. | |
| seed | integer | optional | Best-effort deterministic sampling for reproducible output. | |
| logprobs | boolean | optional | Return log probabilities of output tokens when supported. | |
| top_logprobs | integer | optional | 0–20. Most likely tokens to return per position (requires `logprobs`). | |
| tools | array | optional | Function/tool definitions the model may call. See Tool Calling. | |
| tool_choice | string | object | optional | Control tool use: `auto`, `none`, `required`, or a specific tool. | autononerequired |
| parallel_tool_calls | boolean | optional | Allow multiple tool calls in one turn. Defaults to true on supported models. | |
| response_format | object | optional | Constrain output to `json_object` or `json_schema`. See Structured Outputs. | |
| reasoning_effort | string | optional | For reasoning models: `low`, `medium`, or `high`. | lowmediumhigh |
| user | string | optional | Stable end-user identifier for abuse monitoring. |
The messages array
Each message has a role and content. Roles set who is speaking and how the model treats the turn:
| Parameter | Type | Required | Description |
|---|---|---|---|
| system | role | optional | Sets behavior, tone, and rules for the assistant. Usually the first message. |
| user | role | optional | Input from the end user. Content may be a string or an array of parts. |
| assistant | role | optional | A previous model reply, or a turn containing `tool_calls`. |
| tool | role | optional | The result of executing a tool call, keyed by `tool_call_id`. |
Multimodal content parts
For vision- and audio-capable models, a message's content can be an array of typed parts instead of a plain string. Mix text with image_url (URL or base64 data URI) or input_audio. Parts the selected model does not support are rejected upstream.
{
"role": "user",
"content": [
{ "type": "text", "text": "What is in this image?" },
{ "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
]
}The response object
A non-streaming call returns a chat.completion object (see the panel on the right). Key fields:
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | optional | Unique identifier for the completion. |
| choices | array | optional | The generated choices. `choices[0].message.content` holds the reply text. |
| choices[].finish_reason | string | optional | Why generation stopped: `stop`, `length`, `tool_calls`, or `content_filter`. |
| usage | object | optional | Token accounting: `prompt_tokens`, `completion_tokens`, `total_tokens`. |
| model | string | optional | The model that produced the response. |
Streaming
For OpenAI-compatible and Claude-compatible requests, set stream: true in the JSON body. Gemini streaming can use :streamGenerateContent, alt=sse, or model/client-specific streaming helpers. Streaming responses are delivered as SSE chunks; handle network disconnects and mid-stream errors explicitly.
curl https://onerouter.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.2",
"messages": [{"role": "user", "content": "Write a short launch note."}],
"stream": true
}'Streaming chunk format
With stream: true, the server sends data: SSE lines. Each chunk is a chat.completion.chunk whose choices[0].delta carries the incremental token(s). The stream ends with data: [DONE]. If you set stream_options.include_usage, a final chunk with an empty choices array carries the usage totals.
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""}}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Request"}}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]Model-dependent features
OneRouter keeps protocol compatibility and forwards model-specific parameters where supported. Features such as tool calling, structured output, reasoning, prompt caching, web search, image input, audio input, video generation, and provider-specific options depend on the selected model and upstream provider. Check the model detail page before relying on a feature in production.