Create a chat completion

Create a model response from the conversation history. Supports streaming and non-streaming responses. Compatible with the OpenAI Chat Completions API.

POST /v1/chat/completions

Service root: https://getrouter.ai

Protocol: OpenAI Chat Completions

Authentication: Authorization: Bearer YOUR_API_KEY

Request body

The request body is required. Media type: application/json

Request fields

Field	Type	Required	Description
`model`	`string`	Yes	Model ID
`messages`	`array<object>`	Yes	List of conversation messages
`temperature`	`number`	No	Sampling temperature Default: `1`; Range: 0–2
`top_p`	`number`	No	Nucleus sampling parameter Default: `1`; Range: 0–1
`n`	`integer`	No	Number of generations Default: `1`; Range: 1–∞
`stream`	`boolean`	No	Whether to stream the response Default: `false`
`stream_options`	`object`	No	—
`stop`	`string or array<string>`	No	Stop sequence
`max_tokens`	`integer`	No	Maximum number of generated tokens
`max_completion_tokens`	`integer`	No	Maximum number of completion tokens
`presence_penalty`	`number`	No	Default: `0`; Range: -2–2
`frequency_penalty`	`number`	No	Default: `0`; Range: -2–2
`logit_bias`	`object`	No	—
`user`	`string`	No	—
`tools`	`array<object>`	No	—
`tool_choice`	`string or object`	No	—
`response_format`	`object`	No	—
`seed`	`integer`	No	—
`reasoning_effort`	`string`	No	Reasoning effort (for models that support reasoning) Allowed values: `low`, `medium`, `high`
`modalities`	`array<string>`	No	—
`audio`	`object`	No	—

Example request

curl --request POST \
  --url https://getrouter.ai/v1/chat/completions \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "Hello, introduce yourself."
    }
  ],
  "stream": false,
  "temperature": 1,
  "max_tokens": 1
}'

Responses

Status	Description
`200`	Response created successfully
`400`	Invalid request parameters
`429`	Rate limit exceeded

Success response fields

Field	Type	Required	Description
`id`	`string`	No	—
`object`	`string`	No	—
`created`	`integer`	No	—
`model`	`string`	No	—
`choices`	`array<object>`	No	—
`usage`	`object`	No	—
`system_fingerprint`	`string`	No	—

Example response

{
  "id": "string",
  "object": "object",
  "created": 1,
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 1,
      "message": {
        "role": "system",
        "content": "Hello, introduce yourself.",
        "name": "string",
        "tool_calls": [
          {
            "id": null,
            "type": null,
            "function": null
          }
        ],
        "tool_call_id": "string",
        "reasoning_content": "string"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 1,
    "total_tokens": 1,
    "prompt_tokens_details": {
      "cached_tokens": 1,
      "text_tokens": 1,
      "audio_tokens": 1,
      "image_tokens": 1
    },
    "completion_tokens_details": {
      "text_tokens": 1,
      "audio_tokens": 1,
      "reasoning_tokens": 1
    }
  },
  "system_fingerprint": "string"
}

For complete workflows and examples, read the Chat Completions API Guide.

This page is generated from the public Relay OpenAPI specification. Browse the complete specification in the API Explorer.

#Create a chat completion

#Request body

#Request fields

#Example request

#Responses

#Success response fields

#Example response

#Related guide