Chat Completions

Create OpenAI-compatible text, multimodal, reasoning, and tool-calling completions.

`POST /v1/chat/completions`

Creates a completion from a non-empty message history. The endpoint supports synchronous JSON and Server-Sent Events.

POST /v1/chat/completions
Authorization: Bearer $API_KEY
Content-Type: application/json

Request body

Field	Type	Required	Description
`model`	string	Yes	Complete public model ID.
`messages`	array	Yes	Non-empty conversation history.
`stream`	boolean	No	Return SSE chunks when `true`. Defaults to `false`.
`stream_options.include_usage`	boolean	No	Return the final usage chunk to the client.
`max_completion_tokens`	integer	No	Maximum generated tokens; preferred for current reasoning models.
`max_tokens`	integer	No	Legacy output-token limit accepted by compatible models.
`temperature`	number	No	Sampling temperature supported by the selected model.
`top_p`	number	No	Nucleus sampling value supported by the selected model.
`stop`	string or string[]	No	Stop sequence or sequences.
`tools`	array	No	Function tools in OpenAI format.
`tool_choice`	string or object	No	Tool-selection policy.
`parallel_tool_calls`	boolean	No	Allow compatible models to request multiple tools in parallel.
`response_format`	object	No	JSON mode or a supported structured-output schema.
`reasoning_effort`	string	No	Model-specific reasoning effort on compatible routes.
`frequency_penalty`, `presence_penalty`	number	No	Model-specific repetition controls.
`seed`	integer	No	Best-effort deterministic sampling when supported.
`logprobs`, `top_logprobs`	boolean, integer	No	Token log-probability output when supported.
`n`	integer	No	Number of choices on compatible same-protocol routes.
`user`	string	No	Stable end-user identifier.

A message uses role and content. Text content can be a string. Multimodal user content can be an array of typed parts such as text, image_url, or protocol extensions supported by the selected model. Tool results use role: "tool" and the matching tool_call_id.

Same-protocol routes preserve additional compatible fields, including model-specific reasoning, response format, audio, prediction, and tool extensions. The selected model and upstream-compatible schema remain authoritative for their value ranges and combinations.

Examples

curl "http://127.0.0.1:11113/v1/chat/completions" -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" -d '{
  "model": "openai/gpt-5.2",
  "messages": [
    {"role": "user", "content": "Explain SSE in one sentence."}
  ]
}'

Synchronous response

{
  "id": "chatcmpl_01J...",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "openai/gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "SSE keeps one HTTP response open and delivers events incrementally."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 16,
    "total_tokens": 30
  }
}

model is always rewritten to the public model ID. Tool calls appear in message.tool_calls; reasoning details are present only when the selected model and protocol expose them.

When a Claude model is reached through a cross-protocol route, its thinking blocks are returned in message.reasoning_details (streaming: delta.reasoning_details) in the OpenRouter-compatible shape: reasoning.text items carry signature, reasoning.encrypted items carry data, and both use format: "anthropic-claude-v1" with index set to the block's position. Claude 5 models omit thinking text by default, so text can be empty while signature is present. Send each assistant message back with its reasoning_details unchanged and keep earlier turns unedited, especially between tool calls. Details that are incomplete or not at the start of the assistant turn are not forwarded.

Streaming response

The response content type is text/event-stream. Each event contains one data: JSON chunk. A normal OpenAI-compatible stream ends with data: [DONE].

data: {"id":"chatcmpl_01J...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"One"}}]}

data: {"id":"chatcmpl_01J...","object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":10,"completion_tokens":3,"total_tokens":13}}

data: [DONE]

The gateway always requests upstream usage for billing. The usage-only chunk is forwarded to you only when stream_options.include_usage is true.

Compatibility and restrictions

Current Claude models

Claude 4.7 and later models reject non-default temperature and top_p. Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1, and Claude Mythos 5.1 reject forced tool use, so tool_choice: "required" or a named function returns 400; use auto. Thinking is on by default on Claude 5 models, and a history that ends with an assistant message (prefill) is rejected.

Cross-protocol conversion covers messages, text and image parts, function tools, tool choice, output limits, temperature, top_p, stop sequences, stream events, finish reasons, and usage. Other fields are reported through x-dropped-params when conversion is necessary.

The following are rejected before routing:

Missing model or an empty messages array.
deferred: true, because no deferred-completion retrieval endpoint is exposed.
Client routing fields or a paid service-tier selection.
An image-output model; use its documented image endpoint instead.