Chat Completions

Request basics

• Base URL: https://api.routeapi.ai
• Authentication: Authorization: Bearer $ROUTEAPI_KEY with an API Key starting with sk- (create one on the API Keys page). Management keys starting with rat_ cannot call models.
• Error format: {"error": {"message": "...", "type": "...", "code": "..."}}; status code meanings are in Common Errors.

Chat Completions is the most commonly used conversation API. It is suitable for chat, coding assistants, summarization, classification, tool calling, and multi-turn conversations.

It follows the OpenAI Chat Completions protocol, so an existing OpenAI integration only needs its Base URL and API key changed. The same endpoint also reaches Claude, Gemini, and other models; RouteAPI converts the request and response formats internally.

Endpoint

POST /v1/chat/completions

Full URL:

https://api.routeapi.ai/v1/chat/completions

If a client is configured with a Base URL that omits /v1 (for example https://api.routeapi.ai), requests to /chat/completions are accepted as well; RouteAPI rewrites them to /v1/chat/completions.

Request example

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "Introduce RouteAPI in one sentence" }
    ]
  }'

Request parameters

Field	Type	Required	Description
model	string	Yes	Model ID, must be available to the current account
messages	array	Yes	Conversation message list
stream	boolean	No	Whether to use SSE streaming output, default false
temperature	number	No	Sampling temperature
top_p	number	No	nucleus sampling parameter
max_tokens	number	No	Maximum output token count
max_completion_tokens	number	No	Newer name for the output limit; RouteAPI’s own limit and metering use it in preference to max_tokens when both are set
stop	string/array	No	Custom stop sequences
n	integer	No	Number of candidates to generate; whether more than one is honored depends on the model
presence_penalty	number	No	Presence penalty
frequency_penalty	number	No	Frequency penalty
seed	number	No	Best-effort sampling seed; reproducibility depends on the upstream model
user	string	No	End-user identifier, forwarded to upstream services that support it
tools	array	No	Tool definitions
tool_choice	string/object	No	Tool choice strategy
response_format	object	No	JSON mode or JSON Schema
stream_options	object	No	Extra streaming output options, such as include_usage

Optional fields are forwarded as sent: a field that is absent is not filled in with a default value. See Explicit zero values.

messages format

[
  { "role": "system", "content": "You are a rigorous technical assistant." },
  { "role": "user", "content": "Explain what an API gateway is." }
]

Common roles:

Role	Description
system	System prompt
user	User input
assistant	Historical model response
tool	Tool call result

content may be a plain string or an array of content blocks for multimodal input; see Multimodal Input. When an assistant message returns tool calls, pass that message back unchanged followed by role: "tool" results; see Tool Calling.

Response example

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "RouteAPI is an API gateway for unified access to multiple AI model services."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42
  }
}

finish_reason tells you why generation stopped: stop (natural end), length (hit the output limit), tool_calls (the model wants to call a tool), or content_filter (blocked by a content filter).

Streaming

Set stream: true to receive Server-Sent Events. Each line is a chat.completion.chunk whose choices[0].delta carries the increment, and the stream ends with data: [DONE]:

data: {"id":"chatcmpl_xxx","object":"chat.completion.chunk","created":1730000000,"model":"gpt-5.5","choices":[{"index":0,"delta":{"content":"RouteAPI"},"finish_reason":null}]}

data: {"id":"chatcmpl_xxx","object":"chat.completion.chunk","created":1730000000,"model":"gpt-5.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

By default RouteAPI appends a final chunk with token usage and an empty choices array before data: [DONE]. Send "stream_options": {"include_usage": false} to suppress it (channels that do not support stream_options always send it); usage is still recorded in the console logs. Full event handling and mid-stream errors are covered in Streaming Responses.

SDK configuration

The official OpenAI SDKs work unchanged once the API key and Base URL point at RouteAPI.

OpenAI Python SDK

pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Introduce RouteAPI in one sentence"}],
)

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

OpenAI Node.js SDK

npm install openai

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,
  baseURL: 'https://api.routeapi.ai/v1',
});

const response = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Introduce RouteAPI in one sentence' }],
});

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

LangChain and LiteLLM

Both libraries accept a custom OpenAI-compatible endpoint:

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-5.5",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

import os
import litellm

response = litellm.completion(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Introduce RouteAPI in one sentence"}],
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
)

Other compatible clients

Any client that supports a custom OpenAI Base URL can connect with the same three settings:

1. API key — a RouteAPI API Key starting with sk-.
2. Base URL — https://api.routeapi.ai/v1.
3. Model — a model ID returned by GET /v1/models; see Models.

For ready-made configurations for Codex, Cursor, Claude Code, OpenCode, and other tools, see Migrating from OpenAI.

Differences from the official OpenAI API

Broader model range

The official OpenAI API only serves OpenAI’s own models. The same model field here accepts models from multiple providers — for example gpt-5.5, claude-sonnet-4-5, and gemini-2.5-pro — subject to what is available to your key and group. Which models you can call is answered only by GET /v1/models.

Billing and rate limits are managed by RouteAPI

• Billing uses RouteAPI’s price list, which may differ from the provider’s official price.
• Rate limits follow RouteAPI’s policies rather than the provider’s own limits.
• Balance and key quotas are managed in the RouteAPI console.

See Billing and quotas and Model pricing for details.

Capabilities depend on the selected model

The protocol defines the fields; the model decides which of them actually work. Tool calling, image input, structured output, streaming usage, and reasoning controls depend on the selected model and the upstream service behind it. The models endpoint does not return capability flags, so verify the capabilities you rely on with one real request before depending on them in production.

Explicit zero values

Optional parameters sent explicitly as 0, 0.0, or false are preserved and forwarded, not discarded as “unset”. This lets a client pin temperature: 0 for deterministic sampling. To leave a parameter unset, omit the field entirely rather than sending null.

Upstream errors

When the model service rejects a request, RouteAPI returns the upstream status code and message in the standard error body, with (request id: <id>) appended. Errors produced before routing — invalid key, model not allowed, no available channel — use the codes listed in Common Errors.

Compatibility notes

• The same parameter may be supported differently by different model services.
• If the request includes optional parameters such as tools, response_format, or stream_options, confirm that the selected model supports the corresponding capability first.
• Optional parameters explicitly passed as 0 or false should be treated as user-provided values.
• When combining structured output with tool calling, read the constraints in Structured Outputs first.

Next steps

• Responses — the newer OpenAI protocol, common in coding agents.
• Claude Messages — Anthropic’s native format for Claude-specific features.
• Google Gemini API — Google’s native format.
• Models — which models your key can call and their endpoint types.