API 密钥

API 密钥（API Key）是您访问 TopRouter API 的身份凭证。每个 API 请求都需要携带有效的 API Key 进行认证。

创建 API Key

步骤

1. 登录 您的 TopRouter 账号
2. 进入控制台的 API Key 管理页面
3. 点击「创建新 Key」
4. 为 Key 设置一个便于识别的名称（如 "开发环境"、"生产环境"）
5. 复制生成的 API Key 并妥善保存

⚠️ 重要提示

API Key 只会在创建时完整显示一次。请务必在创建后立即复制并安全保存。如果丢失，您需要创建新的 Key。

在请求中使用 API Key

Authorization Header（推荐）

在 HTTP 请求的 Authorization header 中使用 Bearer Token 格式：

curl https://toprouter.cc/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-4.6-sonnet",
    "messages": [{"role": "user", "content": "你好"}]
  }'

Python SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://toprouter.cc",
    api_key="your-api-key"
)

TypeScript SDK

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://toprouter.cc',
  apiKey: 'your-api-key',
});

环境变量（推荐）

建议将 API Key 存储在环境变量中，避免硬编码在代码里：

# 设置环境变量
export TOPROUTER_API_KEY="your-api-key"

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://toprouter.cc",
    api_key=os.environ.get("TOPROUTER_API_KEY")
)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://toprouter.cc',
  apiKey: process.env.TOPROUTER_API_KEY,
});

管理 API Key

查看已有 Key

登录控制台即可查看所有已创建的 API Key 列表，包括创建时间和最后使用时间。

删除 Key

如果某个 Key 不再使用或被泄露，请立即在控制台中删除。

创建多个 Key

建议为不同用途创建独立的 API Key：

用途	命名示例
开发测试	dev-testing
生产环境	production
CI/CD	ci-pipeline
个人项目	personal-project

安全最佳实践

✅ 应该做

• 使用环境变量 存储 API Key
• 为不同项目 创建独立的 Key
• 定期轮换 API Key
• 设置使用提醒，监控异常消费
• 使用 .env 文件 管理本地开发的密钥

❌ 不应该做

• ❌ 将 API Key 硬编码在源代码中
• ❌ 将 API Key 提交到 Git 仓库
• ❌ 在前端/客户端代码中使用 API Key
• ❌ 通过不安全的渠道分享 API Key
• ❌ 在公开的文档、截图中暴露 API Key

🚨 Key 泄露应急处理

如果发现 API Key 被泄露：

1. 立即登录控制台 删除被泄露的 Key
2. 创建新的 Key 替换被泄露的 Key
3. 检查账户余额 确认是否有异常消费
4. 更新所有使用 被泄露 Key 的应用配置

常见问题

认证失败（401）

如果收到 401 Unauthorized 错误：

1. 确认 API Key 正确无误
2. 确认使用了正确的 Header 格式：Authorization: Bearer your-api-key
3. 确认 Key 未被删除或禁用
4. 检查是否有多余的空格或换行符

API Key 数量限制

每个账户可以创建的 API Key 数量有上限，具体限额请在控制台查看。