OpenAI 兼容协议

OpenAI 兼容协议是业界最广泛支持的 AI API 标准。RouteAPI 完整实现了 OpenAI API 规范，让你可以用现有的 OpenAI SDK、工具和客户端无缝接入，只需切换 Base URL 和 API Key。

协议概述

OpenAI API 定义了一套标准化的 REST 接口，用于对话生成、文本嵌入、模型列表等能力。它的核心优势在于生态成熟：OpenAI 官方 SDK、LangChain、LiteLLM、Cursor、各类编码助手都原生支持这套协议。

RouteAPI 的兼容范围：

完整兼容 OpenAI Chat Completions、Responses、Embeddings、Models 端点
认证方式一致，使用 Authorization: Bearer 请求头
请求响应格式一致，包括流式 SSE 和错误结构
模型 ID 范围更广，可调用 OpenAI、Claude、Gemini、Mistral 等多家模型
显式零值参数保留，显式传入的 0 / false 不会被丢弃

从 OpenAI 官方 API 迁移到 RouteAPI，只需要改两行配置：

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-routeapi-token",        # 换成 RouteAPI Token
    base_url="https://api.routeapi.ai/v1"   # 换成 RouteAPI Base URL
)

其他代码保持不变。

基础地址

https://api.routeapi.ai/v1

所有 OpenAI 兼容端点都使用这个基础地址。如果你的客户端或 SDK 要求填写完整 URL，直接拼接端点路径即可，例如 https://api.routeapi.ai/v1/chat/completions。

认证方式

与 OpenAI 官方 API 完全一致，使用 HTTP Authorization 请求头：

Authorization: Bearer sk-your-routeapi-token
Content-Type: application/json

RouteAPI Token 以 sk- 开头，在控制台的 API Keys 页面生成。请在服务端保存 Token，不要暴露到浏览器、移动端或公开仓库中。

支持的端点总览

端点	用途	详细文档
`/v1/chat/completions`	对话生成，支持多轮对话、工具调用、结构化输出	Chat Completions
`/v1/responses`	OpenAI Responses 协议，适合编码代理和新一代应用框架	Responses
`/v1/embeddings`	文本向量嵌入，用于语义搜索、RAG、相似度计算	Embeddings
`/v1/models`	获取当前账户可用的模型列表	本页下方

适用场景对比

场景	推荐端点	原因
通用聊天、问答、摘要、分类	`/v1/chat/completions`	生态最成熟，兼容范围最广
编码代理（Cursor、Claude Code、Copilot）	`/v1/responses` 或 `/v1/chat/completions`	取决于客户端原生支持的协议
多轮对话、历史记录	`/v1/chat/completions`	`messages` 数组天然支持多轮
工具调用、函数调用	`/v1/chat/completions`	工具定义和结果回传结构最标准
语义搜索、RAG、文档检索	`/v1/embeddings`	返回向量表示
结构化输出、JSON Schema	`/v1/chat/completions` 或 `/v1/responses`	通过 `response_format` 参数控制

具体选择哪个端点，优先看客户端和 SDK 的原生支持。如果客户端明确要求某个协议，按客户端要求选择即可。

SDK 配置

OpenAI Python SDK

安装：

pip install openai

配置 RouteAPI：

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)

只需设置 api_key 和 base_url 两个参数，其他代码与官方 API 完全一致。

OpenAI Node.js SDK

安装：

npm install openai

配置 RouteAPI：

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

LangChain 的 ChatOpenAI 类支持自定义 base_url：

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"
)

response = llm.invoke("请用一句话介绍 RouteAPI")
print(response.content)

LiteLLM

LiteLLM 的 completion() 函数支持自定义 api_base：

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"
)

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

其他兼容客户端

任何支持 OpenAI API 的客户端、工具、框架都可以通过以下配置接入 RouteAPI：

API Key 设置为 RouteAPI Token（sk- 开头）
Base URL 设置为 https://api.routeapi.ai/v1
模型 ID 使用 RouteAPI 支持的模型名称（可通过 /v1/models 查询）

核心请求参数

OpenAI 兼容协议的主要端点共享一套核心参数。以下是常用参数速查表，详细说明请查看各端点的专门文档。

Chat Completions 参数

参数	类型	必填	说明
`model`	string	是	模型 ID，必须是当前账户可用模型
`messages`	array	是	对话消息列表，每条消息包含 `role` 和 `content`
`stream`	boolean	否	是否使用 SSE 流式输出，默认 `false`
`temperature`	number	否	采样温度，取值 `0` 到 `2`，默认 `1`
`top_p`	number	否	nucleus sampling 参数，取值 `0` 到 `1`
`max_tokens`	number	否	最大输出 token 数（旧参数名，部分模型仍需使用）
`max_completion_tokens`	number	否	最大输出 token 数（新参数名）
`tools`	array	否	工具定义列表，用于函数调用
`tool_choice`	string/object	否	工具选择策略（`auto` / `required` / `none` / 指定工具）
`response_format`	object	否	输出格式约束（JSON mode / JSON Schema）
`stream_options`	object	否	流式输出附加选项，如 `include_usage`
`stop`	string/array	否	自定义停止序列
`presence_penalty`	number	否	存在惩罚，取值 `-2` 到 `2`
`frequency_penalty`	number	否	频率惩罚，取值 `-2` 到 `2`
`user`	string	否	终端用户标识，用于滥用检测

详细说明和更多参数请参考 Chat Completions 文档。

Embeddings 参数

参数	类型	必填	说明
`model`	string	是	嵌入模型 ID
`input`	string/array	是	要嵌入的文本，支持单个字符串或字符串数组
`encoding_format`	string	否	返回格式，`float`（默认）或 `base64`
`dimensions`	number	否	输出向量维度，取决于模型是否支持
`user`	string	否	终端用户标识

详细说明请参考 Embeddings 文档。

响应格式

标准响应（非流式）

Chat Completions 标准响应示例：

{
  "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
  }
}

关键字段：

choices[0].message.content — 模型回复的文本内容
choices[0].finish_reason — 结束原因（stop / length / tool_calls / content_filter）
usage — token 用量统计

流式响应（SSE）

设置 stream: true 后返回 Server-Sent Events（SSE）格式的增量数据：

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

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":{"content":" 是"},"finish_reason":null}]}

data: {"id":"chatcmpl_xxx","object":"chat.completion.chunk","created":1730000000,"model":"gpt-5.5","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":24,"completion_tokens":18,"total_tokens":42}}

data: [DONE]

流式响应的特点：

每行以 data: 开头，后跟 JSON 对象
增量内容在 choices[0].delta.content 中
结束时 finish_reason 不为 null
最后一行是 data: [DONE]

如果需要在流式模式下获取 token 用量统计，设置 stream_options: { "include_usage": true }，用量信息会在最后一个数据块中返回。

错误响应

错误响应遵循 OpenAI 的标准格式：

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

常见错误类型：

HTTP 状态码	type	说明
401	`invalid_request_error`	API Key 无效或缺失
429	`rate_limit_error`	触发速率限制
500	`api_error`	服务端内部错误
503	`overloaded_error`	服务过载

详细错误处理请参考错误处理文档。

与官方 OpenAI API 的差异

RouteAPI 的 OpenAI 兼容协议在协议层面完全兼容，但在模型能力、计费和限流上有一些差异：

模型 ID 范围更广

OpenAI 官方 API 只能调用 OpenAI 自己的模型（gpt-4o、gpt-5.5 等）。RouteAPI 支持跨多家供应商的模型：

OpenAI：gpt-4o、gpt-5.5、o3-mini 等
Anthropic Claude：claude-sonnet-4-5、claude-opus-4 等
Google Gemini：gemini-2.0-flash、gemini-2.5-pro 等
Mistral：mistral-large、mistral-small 等
其他：DeepSeek、Qwen、LLaMA 等

通过 /v1/models 端点查询当前账户可用的完整模型列表。

计费和限流由 RouteAPI 管理

计费：按 RouteAPI 的费率表计费，与上游供应商的官方定价可能不同
限流：由 RouteAPI 的速率限制策略控制，而非上游供应商的限流
配额：账户余额和配额由 RouteAPI 管理，在控制台充值和查看

参数支持取决于底层模型

OpenAI 兼容协议定义了一套完整的参数集，但实际支持程度取决于所选模型：

能力	说明
工具调用（`tools`）	取决于模型是否支持函数调用
结构化输出（`response_format`）	取决于模型是否支持 JSON mode 或 JSON Schema
视觉输入（`image_url`）	取决于模型是否支持多模态输入
流式用量（`stream_options.include_usage`）	取决于模型和渠道是否支持流式用量统计
推理控制（`reasoning_effort`）	仅部分推理模型支持

建议在测试环境先验证所选模型对关键参数的支持情况，再在生产环境启用。

显式零值参数的处理

这是一个细节但很重要的差异。在 OpenAI 兼容协议中，可选参数如果显式传入 0、0.0 或 false，RouteAPI 会将其视为用户的显式设置，而不是当作缺省值丢弃。

例如：

{
  "model": "gpt-5.5",
  "messages": [...],
  "temperature": 0,
  "top_p": 1.0
}

这里的 temperature: 0 会被保留并转发给上游模型，而不是因为”值为 0”就被当作未设置。这保证了客户端可以精确控制采样参数。

如果不希望传递某个参数，直接从请求中删除该字段即可，不要传 null 或 0。

兼容性说明

各能力取决于所选模型

OpenAI 兼容协议是一套标准接口定义，但具体能力取决于底层模型：

工具调用：需要模型支持函数调用，且工具定义格式符合模型要求
结构化输出：需要模型支持 JSON mode 或 JSON Schema
视觉输入：需要模型支持图像或多模态输入
流式用量：需要模型和渠道支持在流式模式下返回 token 用量

如果请求包含模型不支持的参数，行为取决于参数类型：

可忽略的参数（如 frequency_penalty）会被静默忽略
关键参数（如 tools）可能触发错误

生产环境建议固定模型 ID，并为关键业务准备失败兜底策略。

参数验证和错误提示

RouteAPI 会对请求参数进行基本验证，如：

必填参数缺失（如 model、messages）
参数类型错误（如 temperature 传了字符串）
参数取值超出范围（如 temperature: 3）

验证失败时返回 400 Bad Request 和详细错误信息。如果请求通过了 RouteAPI 的验证但被上游模型拒绝，会返回 500 或 502 以及上游的原始错误信息。

跨模型迁移注意事项

从一个模型切换到另一个模型时，即使都使用 OpenAI 兼容协议，以下几点需要注意：

上下文长度：不同模型的最大上下文长度不同，超长请求可能被拒绝
工具调用格式：部分模型对工具描述的格式要求更严格
输出风格：相同提示词在不同模型上的输出风格、长度、格式可能有差异
token 计数：不同模型的分词器不同，相同文本的 token 数可能不一致
计费价格：不同模型的单价不同，切换模型可能影响成本

建议在测试环境验证完整流程后再切换生产环境的模型。

/v1/models 端点

/v1/models 端点返回当前账户可用的模型列表，格式与 OpenAI 官方 API 一致。

请求示例

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

响应示例

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "gpt-5.5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "openai",
      "supported_endpoint_types": ["openai", "openai-response"]
    },
    {
      "id": "claude-sonnet-4-5",
      "object": "model",
      "created": 1626777600,
      "owned_by": "anthropic",
      "supported_endpoint_types": ["openai", "anthropic"]
    }
  ]
}

返回的 data 数组是当前 Token 可用的模型，不是平台全量目录。每个模型对象包含：

id — 模型 ID，请求时使用这个值
object — 固定为 "model"
owned_by — 模型所属渠道类型；平台自定义模型为 custom
supported_endpoint_types — RouteAPI 扩展字段，该模型可用的端点类型
created — 固定占位值 1626777600，不是真实上架时间，不要用它排序

顶层多出的 success 字段是 RouteAPI 扩展，OpenAI SDK 只读 data，不影响解析。data 顺序不保证稳定。

建议在应用启动时调用一次 /v1/models，缓存可用模型列表，避免每次请求都查询。字段含义和过滤规则详见 Models。

完整示例

curl 基础对话

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": "system",
        "content": "你是一个严谨的技术助手，回答保持简洁。"
      },
      {
        "role": "user",
        "content": "请用一句话介绍 RouteAPI"
      }
    ],
    "temperature": 0.7
  }'

Python SDK 完整示例

import os
from openai import OpenAI

# 初始化客户端
client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],
    base_url="https://api.routeapi.ai/v1"
)

# 基础对话
def basic_chat():
    response = client.chat.completions.create(
        model="gpt-5.5",
        messages=[
            {"role": "system", "content": "你是一个严谨的技术助手。"},
            {"role": "user", "content": "请用一句话介绍 RouteAPI"}
        ],
        temperature=0.7
    )
    print(response.choices[0].message.content)
    print(f"用量: {response.usage.total_tokens} tokens")

# 流式对话
def streaming_chat():
    stream = client.chat.completions.create(
        model="gpt-5.5",
        messages=[
            {"role": "user", "content": "逐步解释什么是 API 网关"}
        ],
        stream=True,
        stream_options={"include_usage": True}
    )

    for chunk in stream:
        if chunk.choices:
            delta = chunk.choices[0].delta
            if delta.content:
                print(delta.content, end="", flush=True)
        # 最后一个 chunk 包含 usage
        if hasattr(chunk, 'usage') and chunk.usage:
            print(f"\n用量: {chunk.usage.total_tokens} tokens")

# 工具调用
def tool_calling():
    tools = [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "查询指定城市的当前天气",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {
                            "type": "string",
                            "description": "城市名，如 北京"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["city"]
                }
            }
        }
    ]

    messages = [{"role": "user", "content": "北京现在天气怎么样？"}]

    # 第一轮：模型请求调用工具
    response = client.chat.completions.create(
        model="gpt-5.5",
        messages=messages,
        tools=tools,
        tool_choice="auto"
    )

    # 检查是否有工具调用
    if response.choices[0].message.tool_calls:
        # 模拟工具执行
        tool_call = response.choices[0].message.tool_calls[0]
        tool_result = "北京，晴，气温 23 摄氏度，湿度 45%。"

        # 构造第二轮请求
        messages.append(response.choices[0].message)
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": tool_result
        })

        # 第二轮：模型基于工具结果生成回复
        final_response = client.chat.completions.create(
            model="gpt-5.5",
            messages=messages,
            tools=tools
        )
        print(final_response.choices[0].message.content)

# 结构化输出
def structured_output():
    response = client.chat.completions.create(
        model="gpt-5.5",
        messages=[
            {"role": "user", "content": "提取以下文本的关键信息：RouteAPI 是一个 AI API 网关，支持 OpenAI、Claude、Gemini 等模型。"}
        ],
        response_format={
            "type": "json_schema",
            "json_schema": {
                "name": "key_info",
                "strict": True,
                "schema": {
                    "type": "object",
                    "properties": {
                        "product_name": {"type": "string"},
                        "category": {"type": "string"},
                        "supported_models": {
                            "type": "array",
                            "items": {"type": "string"}
                        }
                    },
                    "required": ["product_name", "category", "supported_models"],
                    "additionalProperties": False
                }
            }
        }
    )
    print(response.choices[0].message.content)

if __name__ == "__main__":
    basic_chat()
    print("\n" + "="*50 + "\n")
    streaming_chat()
    print("\n" + "="*50 + "\n")
    tool_calling()
    print("\n" + "="*50 + "\n")
    structured_output()

Node.js SDK 完整示例

import OpenAI from 'openai';

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

// 基础对话
async function basicChat() {
  const response = await client.chat.completions.create({
    model: 'gpt-5.5',
    messages: [
      { role: 'system', content: '你是一个严谨的技术助手。' },
      { role: 'user', content: '请用一句话介绍 RouteAPI' }
    ],
    temperature: 0.7
  });

  console.log(response.choices[0].message.content);
  console.log(`用量: ${response.usage.total_tokens} tokens`);
}

// 流式对话
async function streamingChat() {
  const stream = await client.chat.completions.create({
    model: 'gpt-5.5',
    messages: [
      { role: 'user', content: '逐步解释什么是 API 网关' }
    ],
    stream: true,
    stream_options: { include_usage: true }
  });

  for await (const chunk of stream) {
    if (chunk.choices[0]?.delta?.content) {
      process.stdout.write(chunk.choices[0].delta.content);
    }
    if (chunk.usage) {
      console.log(`\n用量: ${chunk.usage.total_tokens} tokens`);
    }
  }
}

// 工具调用
async function toolCalling() {
  const tools = [
    {
      type: 'function',
      function: {
        name: 'get_weather',
        description: '查询指定城市的当前天气',
        parameters: {
          type: 'object',
          properties: {
            city: {
              type: 'string',
              description: '城市名，如 北京'
            },
            unit: {
              type: 'string',
              enum: ['celsius', 'fahrenheit']
            }
          },
          required: ['city']
        }
      }
    }
  ];

  const messages = [
    { role: 'user', content: '北京现在天气怎么样？' }
  ];

  // 第一轮
  const response = await client.chat.completions.create({
    model: 'gpt-5.5',
    messages: messages,
    tools: tools,
    tool_choice: 'auto'
  });

  // 检查工具调用
  if (response.choices[0].message.tool_calls) {
    const toolCall = response.choices[0].message.tool_calls[0];
    const toolResult = '北京，晴，气温 23 摄氏度，湿度 45%。';

    // 第二轮
    messages.push(response.choices[0].message);
    messages.push({
      role: 'tool',
      tool_call_id: toolCall.id,
      content: toolResult
    });

    const finalResponse = await client.chat.completions.create({
      model: 'gpt-5.5',
      messages: messages,
      tools: tools
    });

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

// 结构化输出
async function structuredOutput() {
  const response = await client.chat.completions.create({
    model: 'gpt-5.5',
    messages: [
      {
        role: 'user',
        content: '提取以下文本的关键信息：RouteAPI 是一个 AI API 网关，支持 OpenAI、Claude、Gemini 等模型。'
      }
    ],
    response_format: {
      type: 'json_schema',
      json_schema: {
        name: 'key_info',
        strict: true,
        schema: {
          type: 'object',
          properties: {
            product_name: { type: 'string' },
            category: { type: 'string' },
            supported_models: {
              type: 'array',
              items: { type: 'string' }
            }
          },
          required: ['product_name', 'category', 'supported_models'],
          additionalProperties: false
        }
      }
    }
  });

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

// 运行示例
async function main() {
  await basicChat();
  console.log('\n' + '='.repeat(50) + '\n');
  await streamingChat();
  console.log('\n' + '='.repeat(50) + '\n');
  await toolCalling();
  console.log('\n' + '='.repeat(50) + '\n');
  await structuredOutput();
}

main().catch(console.error);

接入建议

优先选择 OpenAI 兼容协议，如果你的客户端、SDK、工具原生支持 OpenAI API
固定模型 ID，生产环境不要依赖临时别名或展示名称
记录请求元信息，包括 request ID、model ID、状态码、耗时和 token 用量
启用失败重试，对核心业务启用客户端重试和备用模型方案
验证可选能力，工具调用、结构化输出、视觉输入等能力先在测试环境验证
监控成本和配额，定期检查控制台的用量日志和账单明细
保护 API Key，服务端统一封装 RouteAPI Token，避免业务前端直接持有密钥

如果客户端只支持 Claude Messages 或 Google Gemini 协议，请改用对应的协议端点，参考 Claude Messages 和 Gemini API 文档。