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.

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

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.