TimRouter API 接入指南
第一次接入 TimRouter，先确认所用工具的接口协议，再配置 API Key 和模型。这里给出接入入口、地址对照和首次调用的检查方法；模型权限、可用接口与价格以你的控制台和实时价格页为准。
更新于 。
1. 接入前准备
- 登录 TimRouter 控制台，确认账户余额、API Key 的分组、模型权限和额度。
- 在 实时价格页确认目标模型的完整 ID、计费单位及所选分组。
- 确认客户端需要 Chat Completions、Responses 还是 Anthropic Messages。兼容其中一种接口，不代表另一种或所有工具功能也可用。
2. 按客户端选择 Base URL
| 用途 | 填写地址 | 请求接口 |
|---|---|---|
| OpenAI Python SDK、Cursor 的 OpenAI 兼容配置 | https://api.timrouter.com/v1 | 例如 /v1/chat/completions |
| Codex 自定义模型提供商 | https://api.timrouter.com/v1 | /v1/responses，需确认模型支持 |
| Claude Code CLI 的 ANTHROPIC_BASE_URL | https://api.timrouter.com | 客户端会调用 /v1/messages |
Base URL 是客户端拼接接口路径的起点。Claude Code 的根地址不要再加 /v1；OpenAI SDK 的 base_url则包含 /v1。不要把 /chat/completions或 /messages完整接口路径填入 Base URL 字段。
3. 配置 Key 并确认模型
从控制台选择当前分组有权限的模型，复制完整模型 ID。先在当前终端设置 TIMROUTER_API_KEY 和 TIMROUTER_MODEL；下面的示例只读取环境变量，缺少任一项就停止，不会使用默认模型。密钥不要写入代码仓库。
macOS / Linux 的 Bash 或 Zsh 可以通过交互输入设置本次会话变量：
printf 'TimRouter API Key: '
read -r -s TIMROUTER_API_KEY
printf '\n模型 ID（从控制台复制）: '
read -r TIMROUTER_MODEL
export TIMROUTER_API_KEY TIMROUTER_MODEL
: "${TIMROUTER_API_KEY:?未设置 TIMROUTER_API_KEY}"
: "${TIMROUTER_MODEL:?未设置 TIMROUTER_MODEL}"curl --fail-with-body --silent --show-error \
https://api.timrouter.com/v1/models \
-H "Authorization: Bearer $TIMROUTER_API_KEY"模型列表用于核对 ID，不是推理请求的成功证明。确认列表或控制台中存在目标模型后，按下方对应教程发送一次简短请求。
4. 首次调用如何验收
- 用测试项目和简短提示词执行对应教程。请求可能计费，先查看目标模型价格。
- 确认接口返回成功状态和实际回复；记录调用时间、模型 ID、分组、请求 ID（如有）及返回的 usage。
- 在控制台核对同一时段的用量与扣费记录。列表能返回、Key 验证按钮通过，都不等于模型已经完成首次调用。
- 需要流式输出、工具调用或图像输入时，再分别验证这些能力；简单文本回复不能证明完整 Agent 工作流兼容。
5. 常见接入错误
| 现象 | 先检查 |
|---|---|
| 401 / Invalid API Key | Key 是否有效、完整且传入正确认证字段；程序是否继承当前环境变量。 |
| 404 / 路径不存在 | 是否混用了根地址与 /v1，或在 Base URL 中重复填写接口路径。 |
| 模型不存在 / 无权限 | 模型 ID 是否完全一致，Key 分组是否允许该模型与接口。 |
| 429 / 额度不足 | 根据错误正文区分速率、并发、账户余额与令牌限额；不要连续重复请求。 |
| 超时或 5xx | 保留时间和请求 ID，检查网络与服务状态，并先核对是否已有用量记录。 |
选择你的接入教程
- Claude Code：Anthropic 环境变量配置
- Codex CLI：Responses 提供商配置
- Cursor：OpenAI Base URL 与自定义模型
- Python：OpenAI SDK 最小调用
配置依据
接口地址依据本站 Chat Completions 请求说明、Responses 请求说明与 模型列表说明；各工具的当前官方资料见对应教程。