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	否	最大輸出令牌數（舊參數名，部分模型仍需使用）
`max_completion_tokens`	number	否	最大輸出令牌數（新參數名）
`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 — 令牌用量統計

串流回應（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]

如果需要在串流模式下取得令牌用量統計，設定 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
視覺輸入：需要模型支援影像或多模態輸入
串流用量：需要模型和渠道支援在串流模式下回傳令牌用量

如果請求包含模型不支援的參數，行為取決於參數類型：

可忽略的參數（如 frequency_penalty）會被靜默忽略
關鍵參數（如 tools）可能觸發錯誤

生產環境建議固定模型 ID，並為關鍵業務準備失敗兜底策略。

參數驗證和錯誤提示

RouteAPI 會對請求參數進行基本驗證，如：

必填參數缺失（如 model、messages）
參數類型錯誤（如 temperature 傳了字串）
參數取值超出範圍（如 temperature: 3）

驗證失敗時回傳 400 Bad Request 和詳細錯誤資訊。如果請求通過了 RouteAPI 的驗證但被上游模型拒絕，會回傳 500 或 502 以及上游的原始錯誤資訊。

跨模型遷移注意事項

從一個模型切換到另一個模型時，即使都使用 OpenAI 相容協定，以下幾點需要注意：

上下文長度：不同模型的最大上下文長度不同，超長請求可能被拒絕
工具呼叫格式：部分模型對工具描述的格式要求更嚴格
輸出風格：相同提示詞在不同模型上的輸出風格、長度、格式可能有差異
令牌計數：不同模型的分詞器不同，相同文字的令牌數可能不一致
計費價格：不同模型的單價不同，切換模型可能影響成本

建議在測試環境驗證完整流程後再切換生產環境的模型。

/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、狀態碼、耗時和令牌用量
啟用失敗重試，對核心業務啟用客戶端重試和備用模型方案
驗證可選能力，工具呼叫、結構化輸出、視覺輸入等能力先在測試環境驗證
監控成本和配額，定期檢查控制台的用量日誌和帳單明細
保護 API Key，伺服器端統一封裝 RouteAPI Token，避免業務前端直接持有金鑰

如果客戶端只支援 Claude Messages 或 Google Gemini 協定，請改用對應的協定端點，參考 Claude Messages 和 Gemini API 文件。