Chat completions
Generate a text response with a specific model, or stream the answer as it arrives.
/v1/chat/completions Bearer tokenRequest body
Send JSON with your selected model and conversation messages. Authentication uses a Router API key.
| Parameter | Type | Description |
|---|---|---|
model | string · required | Exact enabled API edition ID. Router preserves your choice. |
messages | array · required | Text messages with system, user, or assistant roles. |
stream | boolean · optional | Return a stream of content deltas instead of a full response. |
max_tokens | integer · optional | Maximum output tokens, within the selected edition’s limit. |
temperature | number · optional | Sampling temperature accepted by the API definition. |
Example request
Set your base URL and API key as described in the Quickstart.
curl "$ROUTER_BASE_URL/chat/completions" \ -H "Authorization: Bearer $ROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemma3:1b", "messages": [ { "role": "user", "content": "Hello!" } ] }'Response
Read the assistant text from choices[0].message.content. A non-streaming response also includes request metadata and provider-reported usage. This abbreviated example uses synthetic values.
{ "id": "request_example", "object": "chat.completion", "model": "gemma3:1b", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "Hello!" }, "finish_reason": "stop" }]}Streaming
With stream: true, consume ordered content deltas and wait for the terminal event. Treat an interrupted stream as incomplete. See the streaming guide.
Errors
Account limits return 429. No matching free provider returns 503 no_provider_available with Retry-After. Global capacity exhaustion returns 503 request_capacity.
Router fails explicitly when it cannot serve the request. See errors and limits for recovery guidance.