GPT API 接入¶

RouteFast 提供 OpenAI 兼容接口。新项目优先使用 Responses API；只有既有工具尚未支持 Responses 时，再使用 Chat Completions。

前提：使用 OpenAI-ChatGPT 分组密钥，并确认目标模型在该密钥的 /v1/models 列表中。可选参数的支持情况见 API 参考。Windows 用户可先按快速开始配置 PowerShell 环境变量。

环境变量¶

export ROUTEFAST_API_KEY="sk-routefast-..."
export ROUTEFAST_BASE_URL="https://api.routefast.ai/v1"

不要把密钥写在浏览器端 JavaScript、移动 App 包或公开代码库中。生产服务应从服务器端密钥管理系统注入。

cURL：Responses API¶

curl -sS --connect-timeout 10 --max-time 120 \
  -D routefast-response-headers.txt \
  "$ROUTEFAST_BASE_URL/responses" \
  -H "Authorization: Bearer $ROUTEFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "写一个 TypeScript 函数，判断字符串是否为回文。",
    "reasoning": {"effort": "medium"}
  }'

保存响应头中的 X-Client-Request-ID（如有）及调用时间；服务端生成的请求 ID 不保证与客户端自行传入的同名头一致。应用也可生成自己的 UUID 作为本地追踪号，但它不是幂等键，不能防止重试后的重复执行或计费。routefast-response-headers.txt 只记录响应头，分享前仍应检查脱敏。

Python SDK¶

安装：

pip install openai

调用：

import os
from openai import OpenAI

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

response = client.responses.create(
    model="gpt-5.6-terra",
    input="用三个要点解释什么是幂等性。",
    reasoning={"effort": "medium"},
)

print(response.output_text)

JavaScript / TypeScript SDK¶

安装：

npm install openai

调用：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROUTEFAST_API_KEY,
  baseURL: "https://api.routefast.ai/v1",
});

const response = await client.responses.create({
  model: "gpt-5.6-terra",
  input: "用三个要点解释什么是幂等性。",
  reasoning: { effort: "medium" },
});

console.log(response.output_text);

流式响应¶

curl -N "$ROUTEFAST_BASE_URL/responses" \
  -H "Authorization: Bearer $ROUTEFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "写一段 100 字以内的产品介绍。",
    "stream": true
  }'

流式接口使用 SSE。客户端要按事件类型解析，不要假定每一行都是完整 JSON，也不要把网络断开简单视为服务端未执行。

Python：识别完整结束¶

以下代码接在前面的 Python client 初始化后。它只收集文本，不执行工具调用；如果你需要工具、多模态或其他事件，需要单独扩展处理并验证。

stream = client.responses.create(
    model="gpt-5.6-terra",
    input="用一句话解释缓存。",
    stream=True,
)
completed = False
try:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "response.completed":
            completed = True
        elif event.type in ("response.failed", "response.incomplete", "error"):
            raise RuntimeError(f"响应未完整成功：{event.type}")
finally:
    stream.close()

if not completed:
    raise RuntimeError("流已断开，但未收到 response.completed；先核对用量再决定重试")
print()

HTTP 200 只说明流已开始；错误和中断仍可能在后续出现，需要继续检查完成事件。OpenAI 流式说明

多轮文本：自行携带必要历史¶

最容易检查的文本多轮方式是在后续请求携带所需历史，而不是假定网关会保存会话：

history = [{"role": "user", "content": "请用一句话解释幂等性。"}]
first = client.responses.create(model="gpt-5.6-terra", input=history)
if first.status != "completed" or not first.output_text:
    raise RuntimeError("第一轮未完整返回文本，不能直接继续")

history.append({"role": "assistant", "content": first.output_text})
history.append({"role": "user", "content": "给一个 HTTP 接口的例子。"})
second = client.responses.create(model="gpt-5.6-terra", input=history)
if second.status != "completed":
    raise RuntimeError("第二轮未完整成功，请检查返回状态和用量")
print(second.output_text)

该例仅适合普通文本对话。工具调用、推理状态和多模态输出不能只保留 output_text；必须按相应协议回传完整所需项，并验证平台兼容性。重发历史会产生输入用量，缓存是否命中以实际 usage 和账单为准。store、previous_response_id 和 Conversations API 在官方服务上的行为不等于 RouteFast 的承诺，本页不依赖这些能力。OpenAI 会话状态

Chat Completions：兼容旧客户端¶

curl -sS "$ROUTEFAST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ROUTEFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {"role": "system", "content": "你是一名简洁的技术助手。"},
      {"role": "user", "content": "解释 HTTP 429。"}
    ],
    "stream": false
  }'

sub2api 对不同上游和协议的处理可能包含转换。若使用工具调用、图片或特殊字段，请先核对接口与兼容性，不要仅凭“OpenAI 兼容”推断与官方所有行为一致。

列出当前可用模型¶

curl -sS "$ROUTEFAST_BASE_URL/models" \
  -H "Authorization: Bearer $ROUTEFAST_API_KEY"

调用前以此接口或控制台模型广场为准。不要在程序中永久硬编码一份从文档复制的模型列表。

超时与重试¶

对连接超时和确认属于临时故障的 502、503、504 使用带抖动的有限退避；上游鉴权等持续配置错误应联系支持；
429 应先区分密钥总额度、金额窗口、并发和上游容量；需要充值或调整额度的错误不应自动重试；
不要自动重试大多数 4xx，应先修正密钥、权限、模型名或参数；
流式请求中断时，先按时间、Key 和模型核对使用记录，保留响应请求 ID 供支持排查，再决定是否重发；
返回 Retry-After 时优先遵循；不要假定每种错误都会包含该头；
限制最大重试次数，并检查 SDK 自带重试，避免与业务层叠加导致重复消耗。具体错误处理见故障排查。