INTEGRATION GUIDE

从令牌到第一条请求

先用小请求确认入口、鉴权和模型名，再写入长期配置。示例不包含真实令牌，也不写死一个可能下线的模型。

1. 选择入口

正式入口用于日常调用；灰云直连用于 Cloudflare 路径异常时的备用排查。两者上线前都必须有独立 DNS、TLS 和真实请求烟测。

正式 API Base 部署前核验
灰云直连 Base 部署前核验
不要在同一个客户端里自动轮询两个入口；出现问题时一次只切换一个变量，保留因果清晰。

2. 创建令牌

  1. 登录控制台，进入令牌页。
  2. 新建最小权限、有限额度、可识别名称的令牌。
  3. 完整令牌只保存到本机密码管理器或安全环境变量。

排查时只确认令牌前缀、权限、分组和过期时间，不把完整 token 发到聊天或工单。

3. 选择当前模型名

打开 模型页，复制当前账号分组可用的准确模型名。示例统一使用 YOUR_MODEL_ID，避免旧文档把已经下线或改名的模型继续写死。

4. OpenAI 兼容

适用于 OpenAI SDK、Aider、Continue、LiteLLM 等支持自定义 Base URL 的客户端。

export OPENAI_BASE_URL="API_BASE"
export OPENAI_API_KEY="YOUR_TOKEN"
export OPENAI_MODEL="YOUR_MODEL_ID"
curl "API_BASE/chat/completions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [{"role": "user", "content": "只回复 ok"}],
    "max_tokens": 16
  }'

5. Anthropic Messages 兼容

会自动追加 /v1/messages 的客户端填写 API origin；手动 curl 或要求完整地址的客户端使用下方完整 URL。正式入口与灰云直连一次只选一个。

正式 Anthropic Origin 部署前核验
灰云 Anthropic Origin 部署前核验 
curl "ANTHROPIC_ORIGIN/v1/messages" \
  -H "x-api-key: YOUR_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "只回复 ok"}]
  }'
curl "DIRECT_ANTHROPIC_ORIGIN/v1/messages" \
  -H "x-api-key: YOUR_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "只回复 ok"}]
  }'

6. 故障分层

  1. 入口：DNS、TLS、域名和 Base URL 是否正确。
  2. 鉴权：401/403 时检查令牌、权限、分组和过期时间。
  3. 模型：404/模型不可用时从模型页重新复制模型名。
  4. 执行：连接建立但无首字时检查流式响应、代理超时和上游日志。
  5. 账单：最终金额以平台请求日志与扣费记录为准，不用页面估算代替对账。