跳到主要内容

认证鉴权

所有 API 请求都需要通过 API Key 进行身份认证。

获取 API Key​

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

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

认证方式总览​

ClawdRouter 当前提供两类认证方式：

终结点 / 协议认证方式说明
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/messagesx-api-key + anthropic-versionAnthropic 原生协议
使用的是同一个平台 API Key

无论你选择 OpenAI 兼容接口、Google 原生接口、视频生成接口还是 Anthropic 原生协议，使用的都是同一个 ClawdRouter 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}

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 使用 x-api-key Header 携带 API Key，并需提供 anthropic-version：

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

请求头说明​

Bearer 认证接口​

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

Anthropic 原生协议​

请求头必填类型说明
x-api-key是string你的 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，格式为 Bearer YOUR_API_KEY
403权限不足检查 API Key 是否有访问对应模型的权限
429请求频率超限降低请求频率，参考限制文档

下一步​