OPENAI 兼容

接口参考

可通过 OpenAI SDK 或直接 HTTPS 请求接入。每个请求都需要携带 API Key。

认证方式

推荐使用 Bearer 认证。为兼容不同客户端，接口同时接受 x-api-key 与 x-goog-api-key。

Authorization: Bearer $HANROUTER_API_KEYx-api-key: $HANROUTER_API_KEYx-goog-api-key: $HANROUTER_API_KEY

管理 API Key

核心接口

GET/v1/models

查询当前 API Key 可调用的模型 ID。

POST/v1/chat/completions

基于消息列表生成模型响应。

直接 HTTP 调用

无需 SDK，使用相同的 Base URL 与 API Key 即可发起请求。

GET /v1/models

curl https://www.hanrouter.com/v1/models \
  -H "Authorization: Bearer $HANROUTER_API_KEY"

POST /v1/chat/completions

curl https://www.hanrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [
      { "role": "user", "content": "Explain this API in one sentence." }
    ],
    "temperature": 0.2
  }'

流式响应

将 stream 设为 true 后，服务会以 Server-Sent Events 返回增量内容；逐条读取 delta，并等待最终完成事件。

cURL

curl -N https://www.hanrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{ "role": "user", "content": "Write a short greeting." }],
    "stream": true
  }'

错误与重试

认证失败不应重试。遇到限流或临时上游故障时，使用指数退避，并在日志中保留请求 ID。

401确认 Key 已启用、复制完整，并且通过任一支持的认证请求头发送。

429降低并发、短暂等待后使用指数退避重试。

5xx仅对幂等或可安全重复的工作，在短暂延迟后重试。