GetRouterDocs
  • English

    • Chat Completions

    Use the OpenAI-compatible Chat Completions endpoint for message-based text generation.

    POST https://getrouter.ai/v1/chat/completions

    Basic request

    curl https://getrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "system", "content": "Answer clearly and concisely."},
      {"role": "user", "content": "What is an API gateway?"}
    ]
  }'

    A non-streaming response contains generated content under:

    choices[0].message.content

    Token usage, when reported by the model, is returned in the usage object.

    Python

    from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://getrouter.ai/v1",
)

response = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {"role": "system", "content": "Answer clearly and concisely."},
        {"role": "user", "content": "What is an API gateway?"},
    ],
)

print(response.choices[0].message.content)

    Node.js / TypeScript

    import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://getrouter.ai/v1',
})

const response = await client.chat.completions.create({
  model: 'MODEL_ID',
  messages: [
    { role: 'system', content: 'Answer clearly and concisely.' },
    { role: 'user', content: 'What is an API gateway?' },
  ],
})

console.log(response.choices[0]?.message.content)

    Message roles

    The API schema supports these roles:

    RolePurpose
    systemHigh-level behavior or context
    developerDeveloper instructions for models that support the role
    userEnd-user input
    assistantPrevious assistant output
    toolResult returned for a tool call

    Common request fields

    FieldDescription
    modelRequired model ID
    messagesRequired ordered conversation messages
    streamReturn incremental chunks when true
    temperatureSampling control supported by the selected model
    top_pNucleus sampling control
    max_tokensMaximum generated tokens for compatible models
    max_completion_tokensCompletion limit used by compatible models
    toolsTool definitions for models that support tool calling
    tool_choiceControls tool selection
    response_formatStructured response configuration for compatible models
    reasoning_effortlow, medium, or high for compatible reasoning models

    Do not send optional fields unless your selected model supports them.

    Multimodal input

    The message content schema supports typed content parts such as text, image URLs, input audio, files, and video URLs. Availability depends on the model.

    Example image input:

    {
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image."},
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/image.jpg"}
        }
      ]
    }
  ]
}

    Tool calling

    When a compatible model returns tool_calls, execute the requested function in your application and append a tool message with the matching tool_call_id. Tool support and exact behavior are model-dependent.

    Streaming

    Set stream to true and read text from each chunk's choices[0].delta.content. See Streaming for complete examples.

    Errors

    • 400 — invalid request fields or unsupported values
    • 401 — missing or invalid API key
    • 429 — rate limit, quota, or capacity restriction
    • Model errors — incorrect model ID or endpoint mismatch

    Next steps