Chat Completions

OpenAI-compatible chat endpoint for text, multimodal input, tools, and streaming when supported by the selected model.

POSThttps://onerouter.com/v1/chat/completions

Troubleshooting

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

ParameterTypeRequiredDescription
Authorizationstring · requiredrequiredBearer token authentication, formatted as `Bearer YOUR_API_KEY`. OpenAI-compatible clients use this header.
Content-Typestring · requiredrequiredMust be `application/json` for chat requests.
x-api-keystringoptionalAlternative key header accepted for clients that send the API key directly.

Request body

ParameterTypeRequiredDescriptionValues
modelstringrequiredModel ID. Use `/v1/models` or the model list page to find available IDs.
messagesarrayrequiredConversation 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.
temperaturenumberoptionalSampling temperature, typically 0–2. Higher is more random. Tune either this or `top_p`.
top_pnumberoptionalNucleus sampling, 0–1. Considers tokens in the top `p` probability mass.
max_tokensintegeroptionalMaximum generated tokens. Newer OpenAI models use `max_completion_tokens`.
streambooleanoptionalReturn SSE deltas instead of one complete JSON response.
truefalse
stream_optionsobjectoptionalStreaming options. Set `{"include_usage": true}` to receive a final usage chunk.
stopstring | arrayoptionalUp to 4 sequences where generation stops; the stop text is not returned.
frequency_penaltynumberoptional−2 to 2. Positive values discourage repeating the same tokens.
presence_penaltynumberoptional−2 to 2. Positive values encourage new topics.
seedintegeroptionalBest-effort deterministic sampling for reproducible output.
logprobsbooleanoptionalReturn log probabilities of output tokens when supported.
top_logprobsintegeroptional0–20. Most likely tokens to return per position (requires `logprobs`).
toolsarrayoptionalFunction/tool definitions the model may call. See Tool Calling.
tool_choicestring | objectoptionalControl tool use: `auto`, `none`, `required`, or a specific tool.
autononerequired
parallel_tool_callsbooleanoptionalAllow multiple tool calls in one turn. Defaults to true on supported models.
response_formatobjectoptionalConstrain output to `json_object` or `json_schema`. See Structured Outputs.
reasoning_effortstringoptionalFor reasoning models: `low`, `medium`, or `high`.
lowmediumhigh
userstringoptionalStable 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:

ParameterTypeRequiredDescription
systemroleoptionalSets behavior, tone, and rules for the assistant. Usually the first message.
userroleoptionalInput from the end user. Content may be a string or an array of parts.
assistantroleoptionalA previous model reply, or a turn containing `tool_calls`.
toolroleoptionalThe 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:

ParameterTypeRequiredDescription
idstringoptionalUnique identifier for the completion.
choicesarrayoptionalThe generated choices. `choices[0].message.content` holds the reply text.
choices[].finish_reasonstringoptionalWhy generation stopped: `stop`, `length`, `tool_calls`, or `content_filter`.
usageobjectoptionalToken accounting: `prompt_tokens`, `completion_tokens`, `total_tokens`.
modelstringoptionalThe 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.

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