SAIRouter API 使用指南

平台如何工作

核心能力

• 统一模型入口：业务代码围绕一个接口抽象，降低多供应商并行接入时的复杂度与变更成本。
• 可观测性：可在平台中查看模型分布、调用趋势、成本结构与状态信息，支持从宏观到请求级别的问题定位。
• 可治理：通过模型启停、限流、策略与回退机制控制风险，减少上游抖动对业务可用性的影响。
• 开发友好：兼容 OpenAI 常见 SDK 和调用格式，便于在已有项目中低成本迁移与灰度验证。

安全

快速开始

curl https://api.sairouter.com/v1/chat/completions \
  -H "Authorization: Bearer sk-sai-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'

认证方式

Authorization: Bearer sk-sai-...

SDK 示例（Node / Python）

下面示例展示了最常见的两种接入方式。实践中建议把 `baseURL` 和 `model` 配置化，并在统一调用层封装重试、超时、日志和错误映射，这样能避免业务代码到处散落重复逻辑。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SAI_API_KEY,
  baseURL: "https://api.sairouter.com/v1",
});

const res = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "你好" }],
});
console.log(res.choices[0]?.message?.content);

from openai import OpenAI

client = OpenAI(
    api_key="sk-sai-...",
    base_url="https://api.sairouter.com/v1",
)

res = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "你好"}],
)
print(res.choices[0].message.content)

请求生命周期

理解生命周期有助于你快速判断问题发生在哪一层。比如 401 多半是鉴权或密钥管理问题，429 往往和配额或并发有关，5xx 可能是上游抖动或网络异常。

1. 客户端携带 API Key 发起请求，并附带模型、消息和可选参数。
2. 平台完成鉴权、参数校验和策略预检查（例如模型是否可用）。
3. 路由层根据策略选择上游并发起调用，必要时进行候选路由切换。
4. 响应返回前会记录调用用量、延迟、状态码和关键追踪信息。
5. 失败场景下返回标准错误结构，便于业务侧统一处理与告警。

1) Chat Completions API

发送对话请求（OpenAI 兼容）。你只需要指定 model 和 messages，其余由 SAIRouter 负责路由选择、失败回退与状态记录。建议在生产环境明确设置 timeout 和重试策略，避免长尾请求拖垮服务线程。

curl https://api.sairouter.com/v1/chat/completions \
  -H "Authorization: Bearer sk-sai-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me a simple Node.js example." }
    ],
    "temperature": 0.7
  }'

model: string (required)
messages: [{ role, content }] (required)
temperature: number (optional)
max_tokens: number (optional)
stream: boolean (optional)

2) Models API（获取模型列表）

用于获取当前可用模型及其能力信息、上下文窗口与价格字段。建议在服务启动时拉取并做短周期缓存，同时定时刷新，以便在模型上下线或价格变更时快速同步。

GET /v1/models
Authorization: Bearer sk-sai-...

常见字段：id、provider、type、contextLength、inputPrice、outputPrice、enabled、features。你可以据此构建模型筛选器、默认模型推荐以及成本估算逻辑。

响应结构

{
  "id": "chatcmpl-xxx",
  "model": "openai/gpt-4o-mini",
  "choices": [{ "index": 0, "message": { "role": "assistant", "content": "..." } }],
  "usage": { "prompt_tokens": 20, "completion_tokens": 60, "total_tokens": 80 }
}

接入最佳实践

• 模型名使用配置中心统一管理，不要硬编码在多个业务模块，避免模型迁移时全链路改代码。
• 统一处理 401/429/5xx，结合指数退避、幂等重试和最大重试次数，避免无界重试引发雪崩。
• 生产环境配置连接超时、读取超时和熔断策略，防止慢请求挤占线程或连接池。
• 日志中记录 request-id、model、provider、latency 和错误码，便于跨团队快速定位问题。

计费与成本

3) 错误处理

公开接口使用统一错误结构，建议按 HTTP 状态码 + code 字段双重处理。实践中可先按状态码做大类分流，再按 code 映射业务策略（如提示重试、切换模型、人工介入），从而避免把所有错误都当作同一种失败。

{
  "code": "UNAUTHORIZED",
  "message": "Invalid API key"
}

4) 速率限制

生产检查清单

• 密钥托管在服务端，避免前端泄露，并对不同环境使用独立密钥。
• 设置连接、读取与总超时，防止请求长期挂起并拖慢整体吞吐。
• 401/429/5xx 均有重试与降级策略，并限制最大重试次数。
• 记录 request-id、错误码、模型、provider 与延迟指标，支持问题复盘。
• 对高峰流量设置预算上限、异常告警与应急开关。

5) 调试与文档链接

排障指引

• 先确认 API Key 是否正确、是否过期、是否误用了其他环境密钥。
• 检查目标模型是否启用，以及是否在当前区域或环境可用。
• 查看状态页与用量页，判断是上游波动、流量突增还是限流触发。
• 保留失败时间、request-id、错误码和样例请求，便于快速复现和定位。

帮助与支持

术语表

6) FAQ