跳到主要内容

认证鉴权

所有 API 请求都需要通过 API Key 进行身份认证。对外调用 ClawdRouter 代理 URL 时，统一使用 Authorization: Bearer YOUR_API_KEY；如果你使用 Anthropic SDK 或 Google SDK 指向该代理 URL，SDK 自动发送的 x-api-key 或 x-goog-api-key 也会由平台代理层在内部归一化处理。

获取 API Key​

  1. 登录 ClawdRouter 平台控制台
  2. 进入 密钥管理页面
  3. 点击「新增密钥」
  4. 复制生成的 Key 并妥善保存
安全提示

API Key 是你的账户凭证，请务必妥善保管。不要在客户端代码、公开仓库或日志中暴露你的 API Key。

认证方式总览​

ClawdRouter 当前对外统一使用 Bearer 认证：

终结点 / 协议认证方式说明
POST /v1/chat/completionsAuthorization: Bearer YOUR_API_KEYOpenAI 兼容聊天接口
POST /v1/responsesAuthorization: Bearer YOUR_API_KEYOpenAI Responses 协议
POST /v1/images/generationsAuthorization: Bearer YOUR_API_KEYOpenAI 图片生成
POST /v1/video/generationsAuthorization: Bearer YOUR_API_KEYVeo 视频生成
POST /v1beta/models/{model}:{method}Authorization: Bearer YOUR_API_KEYGoogle Gemini 原生多模态接口
POST /v1/messagesAuthorization: Bearer YOUR_API_KEYAnthropic 原生协议，请额外传入 anthropic-version
使用的是同一个平台 API Key

无论你选择 OpenAI 兼容接口、Google 原生接口、视频生成接口还是 Anthropic 原生协议，使用的都是同一个 ClawdRouter API Key。对外文档统一使用 Authorization: Bearer YOUR_API_KEY；若 SDK 自动发送 x-api-key 或 x-goog-api-key，平台也会在内部归一化处理。

Bearer 认证​

以下接口统一使用 Authorization: Bearer YOUR_API_KEY：

  • POST /v1/chat/completions
  • POST /v1/responses
  • POST /v1/images/generations
  • POST /v1/video/generations
  • POST /v1beta/models/{model}:{method}
  • POST /v1/messages

OpenAI 协议 (/v1/chat/completions)​

在请求的 Authorization Header 中携带 API Key：

Authorization: Bearer YOUR_API_KEY
curl __DOCS_API_ORIGIN__/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "你好"}]}'

视频生成接口 (/v1/video/generations)​

curl __DOCS_API_ORIGIN__/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "model": "veo-3.1-fast-generate-001",
    "prompt": "A cute small bird dancing on a tree branch, moving rhythmically to cheerful music. The bird gently sways its body, lightly flaps its wings, and playfully tilts its head. Bright forest background with soft sunlight and subtle shadows. Semi-realistic, slightly cartoon style, vivid but not over-saturated colors. Static camera, centered subject, smooth motion, medium detail. 720p resolution, clear and stable output.",
    "duration": 4,
    "metadata": {
      "durationSeconds": 4,
      "aspectRatio": "16:9",
      "resolution": "720p",
      "negativePrompt": "low quality, blurry, distorted",
      "personGeneration": "allow_adult",
      "generateAudio": true
    }
  }'

Anthropic 原生协议​

POST /v1/messages 对外仍统一使用 Authorization Header 携带平台 API Key，并需提供 anthropic-version。如果你使用 Anthropic SDK 指向 ClawdRouter 代理 URL，SDK 自动发送的 x-api-key 会由平台代理层归一化处理。

Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
curl __DOCS_API_ORIGIN__/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "你好"}]}'

对于 Google 原生接口也是同样规则：直接发 HTTP 请求时统一使用 Authorization: Bearer YOUR_API_KEY；如果 Google SDK 或厂商示例代码自动发送 x-goog-api-key，平台代理层会在内部转换。

请求头说明​

Bearer 认证接口​

请求头必填类型说明
Authorization是string格式为 Bearer YOUR_API_KEY，用于身份认证
Content-Type是string固定为 application/json
Request-Id否string客户系统生成的唯一业务标识，用于请求追踪和问题排查

Anthropic 原生协议​

请求头必填类型说明
Authorization是string格式为 Bearer YOUR_API_KEY，用于身份认证
anthropic-version是stringAPI 版本，如 2023-06-01
Content-Type是string固定为 application/json

Request-Id​

你可以在请求头中传入自定义的 Request-Id，用于：

  • 请求追踪 — 将你的业务系统中的请求与 ClawdRouter 的调用关联
  • 问题排查 — 在联系技术支持时提供 Request-Id 可加快问题定位
curl __DOCS_API_ORIGIN__/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Request-Id: your-unique-request-id-123" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "你好"}]}'

在 SDK 中使用​

Python (OpenAI SDK / 兼容接口)​

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="__DOCS_API_ORIGIN__/v1",
)

Python (Anthropic SDK)​

import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_API_KEY",
    base_url="__DOCS_API_ORIGIN__",
)

Node.js (OpenAI SDK / 兼容接口)​

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "__DOCS_API_ORIGIN__/v1",
});

Node.js (Anthropic SDK)​

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "YOUR_API_KEY",
  baseURL: "__DOCS_API_ORIGIN__",
});

常见认证错误​

状态码说明解决方法
401API Key 无效或缺失检查 Header 中是否正确携带了 Authorization；若使用 Anthropic / Google SDK，请确认请求确实带出了 x-api-key 或 x-goog-api-key
403权限不足检查 API Key 是否有访问对应模型的权限
429请求频率超限降低请求频率，参考限制文档

下一步​