CanalAPI
Getting started

简介

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

60 秒内上手
在控制台获取密钥，运行下方示例，即刻完成。
获取 API 密钥 →
完整文档站
更详尽的指南、教程与 API 参考，请访问专门文档站。
docs.canalapi.com →
→ 对话补全
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-opus-4-6",
    "messages": [{"role":"user","content":"Hello"}]
  }'

响应示例

application/json
{
  "id": "chatcmpl_8K2m3",
  "object": "chat.completion",
  "created": 1745078400,
  "model": "claude-opus-4-6",
  "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_ 前缀开头，可在控制台为不同环境（开发 / 测试 / 生产）创建独立密钥。

i
提示： 将密钥保存在环境变量中（如 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可选number0–2。值越高，随机性越强。默认值取决于模型。
max_tokens可选integer补全 token 的上限。默认值取决于模型。
tools可选arrayFunction Calling 工具定义。请求 schema 与 OpenAI / Anthropic 原生格式一致。

流式输出示例

Python · SSE
stream = client.chat.completions.create(
  model="claude-opus-4-6",
  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/responsesOpenAI Responses API 兼容端点
POST/v1/messagesAnthropic Messages API 原生端点（可直接对接 Claude SDK；count_tokens 子端点免费）
GET/v1/models查询可用模型列表（公开端点，无需鉴权）
GET/v1/dashboard/billing/credit_grants返回 OpenAI 兼容的账户余额摘要

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

原生 GeminiPOST/v1beta/models/*:generateContent

除 OpenAI 兼容的 /v1 外，CanalAPI 还在 /v1beta 暴露原生 Gemini 接口。只需把 Gemini SDK（@google/generative-ai）的 base_url 指向 https://api.canalapi.com/v1beta，并用 CanalAPI 密钥鉴权，即可零修改对接 generateContent 与 streamGenerateContent。

i
鉴权： 支持两种请求头：Authorization: Bearer <密钥> 与 x-goog-api-key: <密钥>，两者等价。出于安全考虑，不支持 ?key= 查询参数（避免密钥落入访问日志）。

生成内容

cURL
# 把 Gemini SDK 的 base_url 指向 CanalAPI 的 /v1beta，用 CanalAPI 密钥鉴权
curl "https://api.canalapi.com/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: $CANAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "Hello" }] }]
  }'

流式生成

cURL · SSE
# 流式：streamGenerateContent + ?alt=sse；鉴权头同样可用 Authorization: Bearer
curl "https://api.canalapi.com/v1beta/models/gemini-3.1-pro-preview:streamGenerateContent?alt=sse" \
  -H "Authorization: Bearer $CANAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "Write a haiku." }] }]
  }'

Gemini SDK 接入

TypeScript
import { GoogleGenerativeAI } from "@google/generative-ai";

// 把 SDK 的 baseUrl 指向 CanalAPI 的 /v1beta，apiKey 用 CanalAPI 密钥
const genAI = new GoogleGenerativeAI(process.env.CANAL_KEY, {
  baseUrl: "https://api.canalapi.com/v1beta",
});

const model = genAI.getGenerativeModel({ model: "gemini-3.1-pro-preview" });
const result = await model.generateContent("Hello");
console.log(result.response.text());

图像编辑POST/v1/images/edits

在已有图片基础上按提示词进行编辑（可选传入遮罩 mask）。请求为 multipart/form-data，与 OpenAI Images Edit 兼容；按生成图片数计费。

字段类型描述
image必填file待编辑的源图片文件（image/jpeg · image/png · image/webp，单文件 ≤ 25MB）。
prompt必填string编辑指令文本，描述期望的修改。
mask可选file可选遮罩图片，透明区域表示需要重绘的部分。
model可选string模型标识符，默认 dall-e-2。也可传入 gpt-image-1 等图像模型。
n可选integer生成图片数量（1–10），默认 1。
size可选string输出图片尺寸，如 1024x1024。
cURL
# multipart/form-data：image + prompt 必填，mask 可选
curl https://api.canalapi.com/v1/images/edits \
  -H "Authorization: Bearer $CANAL_KEY" \
  -F image="@source.png" \
  -F prompt="Add a red hat to the cat" \
  -F model="gpt-image-1" \
  -F n=1 \
  -F size="1024x1024"

图像变体/v1/images/variations

基于源图片生成相似的变体，无需提示词；同为 multipart/form-data，仅需 image 字段（model / n / size 可选）。

cURL
# multipart/form-data：仅需 image
curl https://api.canalapi.com/v1/images/variations \
  -H "Authorization: Bearer $CANAL_KEY" \
  -F image="@source.png" \
  -F n=2 \
  -F size="1024x1024"
i
支持格式： image 与 mask 仅接受 image/jpeg、image/png、image/webp，单文件不超过 25MB。

错误与重试

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

状态码含义处理方式
400bad_request检查请求体 — 可能是无效 model 或格式错误的 messages。
401unauthenticated密钥缺失、无效或已吊销。请在控制台创建新密钥。
402insufficient_balance余额不足。完成充值后重试。
429rate_limited已超出每分钟请求上限。请按响应头 Retry-After 与 X-RateLimit-* 退避重试。
502/503upstream_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 密钥 →
← 简介对话补全 →