Chat Completions

Chat Completions 是最常用的对话接口，适合普通聊天、编程助手、摘要、分类、工具调用和多轮对话。

它遵循 OpenAI Chat Completions 协议，已有的 OpenAI 接入只需替换 Base URL 和 API Key。同一个端点也能调用 Claude、Gemini 等模型，协议差异由 RouteAPI 在内部转换。

Endpoint

POST /v1/chat/completions

完整地址：

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

如果客户端把 Base URL 配成不带 /v1（例如 https://api.routeapi.ai），访问 /chat/completions 也可以，RouteAPI 会把它改写成 /v1/chat/completions。

请求示例

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": "请用一句话介绍 RouteAPI" }
    ]
  }'

请求参数

字段	类型	必填	说明
`model`	string	是	模型 ID，必须是当前账户可用模型
`messages`	array	是	对话消息列表
`stream`	boolean	否	是否使用 SSE 流式输出，默认 `false`
`temperature`	number	否	采样温度
`top_p`	number	否	nucleus sampling 参数
`max_tokens`	number	否	最大输出 token 数
`max_completion_tokens`	number	否	输出上限的新字段名；与 `max_tokens` 同时存在时，RouteAPI 自身的上限判断与计量以它为准
`stop`	string/array	否	自定义停止序列
`n`	integer	否	生成候选数；是否真的返回多个候选取决于模型
`presence_penalty`	number	否	存在惩罚
`frequency_penalty`	number	否	频率惩罚
`seed`	number	否	尽力而为的采样种子；能否复现取决于上游模型
`user`	string	否	终端用户标识，会透传给支持该字段的上游
`tools`	array	否	工具定义
`tool_choice`	string/object	否	工具选择策略
`response_format`	object	否	JSON mode 或 JSON Schema
`stream_options`	object	否	流式输出附加选项，例如 `include_usage`

可选字段按原样转发：不传的字段不会被补上默认值。详见下文「显式零值」。

messages 格式

[
  { "role": "system", "content": "你是一个严谨的技术助手。" },
  { "role": "user", "content": "解释什么是 API 网关。" }
]

常见 role：

Role	说明
`system`	系统提示词
`user`	用户输入
`assistant`	模型历史回复
`tool`	工具调用结果

content 可以是纯字符串，也可以是内容块数组，用于多模态输入，见多模态输入。assistant 消息返回工具调用时，需要把该消息原样传回，再追加 role: "tool" 的结果，见工具调用。

响应示例

{
  "id": "chatcmpl_xxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "RouteAPI 是一个统一管理多家 AI 模型供应商的 API 网关。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 18,
    "total_tokens": 42
  }
}

finish_reason 表示生成结束的原因：stop（自然结束）、length（达到输出上限）、tool_calls（模型请求调用工具）、content_filter（被内容过滤拦截）。

流式输出

设置 stream: true 后返回 Server-Sent Events。每行是一个 chat.completion.chunk，增量内容在 choices[0].delta 里，流以 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]

默认情况下，RouteAPI 会在 data: [DONE] 之前追加一个携带 token 用量、choices 为空的数据块。传 "stream_options": {"include_usage": false} 可将其关闭（不支持 stream_options 的渠道则始终返回）；用量仍会记录在控制台日志里。完整的逐事件处理与流中错误见流式响应。

SDK 配置

官方 OpenAI SDK 只需把 API Key 和 Base URL 指向 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": "请用一句话介绍 RouteAPI"}],
)

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: '请用一句话介绍 RouteAPI' }],
});

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

LangChain 与 LiteLLM

这两个库都支持自定义 OpenAI 兼容端点：

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": "请用一句话介绍 RouteAPI"}],
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
)

其他兼容客户端

任何支持自定义 OpenAI Base URL 的客户端，用同样三项配置即可接入：

API Key — sk- 开头的 RouteAPI API Key。
Base URL — https://api.routeapi.ai/v1。
模型 — GET /v1/models 返回的模型 ID，见 Models。

Codex、Cursor、Claude Code、OpenCode 等工具的现成配置见从 OpenAI 迁移。

与官方 OpenAI API 的差异

模型范围更广

官方 OpenAI API 只能调用 OpenAI 自家模型。这里的 model 字段可以填多家供应商的模型，例如 gpt-5.5、claude-sonnet-4-5、gemini-2.5-pro，具体取决于你的 Key 和分组能用哪些。能调用哪些模型只能以 GET /v1/models 的返回为准。

计费与限流由 RouteAPI 管理

计费按 RouteAPI 的价格表，可能与供应商官方价格不同。
限流按 RouteAPI 的策略，而不是供应商自己的限额。
余额与 Key 额度都在 RouteAPI 控制台管理。

详见计费与额度和模型定价。

能力取决于所选模型

协议只定义字段，字段是否真正生效取决于模型。工具调用、图像输入、结构化输出、流式用量和推理控制都取决于所选模型及其背后的上游服务。模型列表接口不返回能力标记，依赖某项能力前请先用一次真实请求验证。

显式零值

显式传 0、0.0 或 false 的可选参数会被保留并转发，不会因为”值是 0”被当作未设置丢弃。这样可以固定 temperature: 0 做确定性采样。想让某个参数保持未设置，直接删掉该字段，不要传 null。

上游错误

模型服务拒绝请求时，RouteAPI 返回上游的状态码和消息，使用标准错误结构，并在 message 末尾附加 (request id: <id>)。路由之前产生的错误——Key 无效、模型无权限、无可用渠道——使用常见错误里列出的错误码。

兼容性提醒

同一个参数在不同模型服务中的支持程度可能不同。
如果请求包含 tools、response_format、stream_options 等可选参数，请先确认所选模型支持对应能力。
明确传入 0 或 false 的可选参数应被视为用户显式设置。
结构化输出与工具调用一起使用时，先阅读结构化输出里的约束。

下一步

Responses — 更新的 OpenAI 协议，编码代理常用。
Claude Messages — Anthropic 原生格式，可用 Claude 专有能力。
Google Gemini API — Google 原生格式。
Models — 你的 Key 能调用哪些模型及其端点类型。