Chat Completions API

Send a sequence of messages to a model and receive a completion. This is the primary AnyRouter inference endpoint and a drop-in replacement for OpenAI's POST /v1/chat/completions — point your OpenAI client at the AnyRouter base URL and it works unchanged.

Request

You can also force a provider for a single request with X-AnyRouter-Provider: openai, or a comma-separated fallback list such as X-AnyRouter-Provider: groq,openai. Every response returns X-Request-ID for support correlation and X-AnyRouter-Provider for the upstream that served it.

Routing preferences

provider biases or constrains upstream selection without changing the model id:

{
  "provider": {
    "only": ["OpenAI", "Groq"],
    "order": ["Groq", "OpenAI"],
    "sort": "ttft",
    "allow_fallbacks": true,
    "max_price": {
      "prompt": "1.00",
      "completion": "2.00"
    }
  }
}

Use it when you want a lower-latency provider, a strict price ceiling, or a reproducible preferred backend order. AnyRouter tracks live TTFT and TPS per upstream from real traffic and re-ranks every request.

Shortcut suffixes on the model id pick the sort for you: model:floor → cost, model:fast → ttft, model:nitro → tps. Legacy names price, latency, and throughput are accepted aliases for cost, ttft, and tps. Supported routing fields are only, ignore, order, sort, allow_fallbacks, max_price.prompt, max_price.completion, preferred_max_latency, and preferred_min_throughput; other fields are accepted for client compatibility but do not affect local routing.

Response

{
  "id": "chatcmpl-8yWq4JqLfEjJ9L",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "anthropic/claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "NAT maps many private IP addresses to one public IP so devices behind a router can share a single internet connection."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 30,
    "total_tokens": 58,
    "cost": 0.000342
  }
}

Cost of a request

usage.cost is the USD amount charged to your credits for the request. It is 0 when nothing was charged, for example a free model or a request made with your own provider key (BYOK).

Where it appears:

• Non-streaming: on every response that includes usage.
• Streaming: on the chunk that carries usage. That is usually the final usage chunk (an empty choices array), which is sent once the stream ends. When a provider reports usage on the finish chunk instead, usage.cost is on that chunk, and it is never held back for billing. AnyRouter always requests the usage from the provider, whether or not you set stream_options.include_usage. No chunk is added or reordered. A provider that repeats usage on every content chunk gets usage.cost only on the finish chunk.
• /responses: usage.cost is the charged amount on non-streaming responses and on the terminal response.completed event of a stream. The input/output split in usage.cost_details is not returned, because it never added up to the charge for cached tokens or non-list prices. /messages reports the charged amount as usage.cost too: on the response, or on the final message_delta of a stream (Messages).

The value is the amount debited from your credits, so it matches your usage history.

Once a chunk shows usage.cost, that amount is charged even if your client disconnects, or the provider drops the connection, before the stream ends.

Examples

curl https://anyrouter.dev/api/v1/chat/completions \
  -H "Authorization: Bearer sk-ar-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "messages": [
      { "role": "system", "content": "You are a concise assistant." },
      { "role": "user", "content": "Explain NAT in one sentence." }
    ],
    "max_tokens": 200
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://anyrouter.dev/api/v1",
    api_key="sk-ar-your-key",
)

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain NAT in one sentence."},
    ],
    max_tokens=200,
)

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

import OpenAI from "openai"

const openai = new OpenAI({
  baseURL: "https://anyrouter.dev/api/v1",
  apiKey: "sk-ar-your-key",
})

const completion = await openai.chat.completions.create({
  model: "anthropic/claude-sonnet-4-6",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Explain NAT in one sentence." },
  ],
  max_tokens: 200,
})

console.log(completion.choices[0].message.content)

Tool use

Pass a tools array with function schemas, then handle any returned tool_calls:

curl https://anyrouter.dev/api/v1/chat/completions \
  -H "Authorization: Bearer sk-ar-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [
      { "role": "user", "content": "What is the weather in Tokyo?" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather for a city",
          "parameters": {
            "type": "object",
            "properties": { "city": { "type": "string" } },
            "required": ["city"]
          }
        }
      }
    ]
  }'

const response = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "What is the weather in Tokyo?" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Get the current weather for a city",
        parameters: {
          type: "object",
          properties: { city: { type: "string" } },
          required: ["city"],
        },
      },
    },
  ],
})

See Tool use for a deeper walkthrough.

Errors

All errors follow the standard AnyRouter JSON envelope with a stable error.code.

See Errors for the full status table and retry recipes.