Getting started

简介

CanalAPI 是聚合 600+ 大语言模型、图像和音频模型的统一网关。使用任意 OpenAI 兼容客户端 — 将 base_url 指向 https://api.canalapi.com/v1，传入您的密钥，即可开始构建。

60 秒内上手

在控制台获取密钥，运行下方示例，即刻完成。

获取 API 密钥 →

→ 对话补全

OpenAI / Claude / Gemini / 国产模型统一格式调用

→ 端点一览

Chat / Embeddings / Images / Audio / Moderations 等完整能力

→ 认证

Bearer Token 或 x-api-key 双协议支持

→ 流式输出

SSE 流式返回，OpenAI 兼容

快速开始

您只需要两样东西：一个 API 密钥（从控制台获取）和一个模型标识符。以下是最简单的请求示例：

cURL

# Any OpenAI-compatible client works — just swap the base URL
curl https://api.canalapi.com/v1/chat/completions \
  -H "Authorization: Bearer $CANAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-4-sonnet",
    "messages": [{"role":"user","content":"Hello"}]
  }'

响应示例

application/json

{
  "id": "chatcmpl_8K2m3",
  "object": "chat.completion",
  "created": 1745078400,
  "model": "claude-4-sonnet",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hi there!" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 8, "completion_tokens": 3, "total_tokens": 11 }
}

认证

所有受保护端点支持两种鉴权头：Authorization: Bearer <密钥>（OpenAI / 通用风格）与 x-api-key: <密钥>（Anthropic SDK 风格）。两者同时出现时以 Authorization 为准。密钥以 ca_sk_live_ 前缀开头，可在控制台为不同环境（开发 / 测试 / 生产）创建独立密钥。

提示： 将密钥保存在环境变量中（如 CANAL_KEY），任意 OpenAI 兼容 SDK 只需把 base URL 指向 https://api.canalapi.com/v1，即可零修改对接。

对话补全POST/v1/chat/completions

创建对话补全。与 OpenAI 的 chat/completions 完全兼容 — 相同参数、相同响应格式，并自动选择上游渠道。

请求体

字段	类型	描述
model必填	string	模型标识符（model slug）。请求 /v1/models 获取实时可用模型列表，或访问定价页查看。
messages必填	array	对话数组，元素为 { role, content } 对象。角色支持 system、user、assistant。
stream可选	boolean	若为 true，以 SSE 方式逐 token 流式返回。默认 false。
temperature可选	number	0–2。值越高，随机性越强。默认值取决于模型。
max_tokens可选	integer	补全 token 的上限。默认值取决于模型。
tools可选	array	Function Calling 工具定义。请求 schema 与 OpenAI / Anthropic 原生格式一致。

流式输出示例

Python · SSE

stream = client.chat.completions.create(
  model="claude-4-sonnet",
  messages=[{"role": "user", "content": "Write a haiku."}],
  stream=True,
)
for chunk in stream:
  print(chunk.choices[0].delta.content or "", end="")

端点一览

所有端点共享同一密钥与鉴权方式。下表列出目前已上线的 OpenAI 兼容与厂商原生端点：

方法	路径	用途
POST	/v1/embeddings	生成文本向量（OpenAI Embeddings 兼容）
POST	/v1/images/generations	图像生成（DALL·E 兼容；同名 /edits 与 /variations 也已支持）
POST	/v1/audio/transcriptions	语音转文字（Whisper 兼容；同时支持 /audio/translations）
POST	/v1/audio/speech	文字转语音（TTS）
POST	/v1/moderations	内容审核（通常免费）
POST	/v1/responses	OpenAI Responses API 兼容端点
POST	/v1/messages	Anthropic Messages API 原生端点（可直接对接 Claude SDK；count_tokens 子端点免费）
GET	/v1/models	查询可用模型列表（公开端点，无需鉴权）
GET	/v1/dashboard/billing/credit_grants	返回 OpenAI 兼容的账户余额摘要

详细请求参数与厂商差异以原厂 API 规范为准；CanalAPI 透传所有标准字段。

错误与重试

CanalAPI 使用标准 HTTP 状态码，错误响应遵循 OpenAI 风格 { error: { message, type, code } }。遇到上游 5xx 错误时自动跨健康渠道重试 — 只有在路由池耗尽后才向客户端返回错误。

状态码	含义	处理方式
400	bad_request	检查请求体 — 可能是无效 model 或格式错误的 messages。
401	unauthenticated	密钥缺失、无效或已吊销。请在控制台创建新密钥。
402	insufficient_balance	余额不足。完成充值后重试。
429	rate_limited	已超出每分钟请求上限。请按响应头 Retry-After 与 X-RateLimit-* 退避重试。
502/503	upstream_error	上游全部不可用且已自动重试。若持续出现，请联系客服。

✓

自动重试： 对上游 5xx 错误，CanalAPI 在路由池内的健康渠道之间自动重试；客户端只需对 429 / 502 / 503 实现常规指数退避。

SDK 接入

CanalAPI 不发布自有 SDK，而是与主流厂商官方 SDK 完全兼容 — 只要把 base URL 与密钥替换为 CanalAPI，您现有的代码无需改动即可运行。

OpenAI 官方 SDK

适用于 /v1/chat/completions、/v1/embeddings、/v1/images/*、/v1/audio/*、/v1/moderations、/v1/responses 等 OpenAI 兼容端点。把 base_url 改为 https://api.canalapi.com/v1 即可。

pip install openai • npm i openai

Anthropic 官方 SDK

适用于 /v1/messages 原生端点。将 base_url 指向 https://api.canalapi.com，并通过 x-api-key 头传入您的 CanalAPI 密钥即可。

pip install anthropic • npm i @anthropic-ai/sdk

→

准备好开始构建了吗？

获取您的第一个 API 密钥，两分钟内完成首次调用。

获取 API 密钥 →

← 简介对话补全 →