Getting started

简介

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

60 秒内上手

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

获取 API 密钥 →

→ 对话补全

GPT-4o、Claude 4、Gemini 2.5 — 统一格式

→ 向量嵌入

OpenAI 和 BGE 向量，支持 8K+ 上下文

→ 自动路由

跨渠道自动故障转移

→ 流式输出

SSE，逐 token 输出，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 ... 请求头传递您的密钥。密钥有作用域 — 可在控制台为不同环境（开发 / 测试 / 生产）创建独立密钥。

提示： 在环境变量中设置 CANAL_KEY，任意 OpenAI SDK 都能通过 OPENAI_API_KEY 自动读取 — 只需修改 baseURL 即可完全兼容。

对话补全POST/v1/chat/completions

创建对话补全。与 OpenAI 的 chat/completions 完全兼容 — 相同参数，相同响应格式。

请求体

字段	类型	描述
model必填	string	模型标识符，如 claude-4-sonnet、gpt-4o。查看完整模型列表。
messages必填	array	对话数组，元素为 { role, content } 对象。角色：system、user、assistant。
stream可选	boolean	若为 true，以 SSE 方式流式返回 token。默认 false。
temperature可选	number	0–2。值越高，随机性越强。默认 1。
max_tokens可选	integer	补全 token 的上限。默认值取决于模型。
tools可选	array	函数调用的工具定义。

流式输出示例

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="")

错误与重试

CanalAPI 使用标准 HTTP 状态码。遇到上游 5xx 错误时自动跨健康渠道重试 — 只有在路由池耗尽后才返回错误。

状态码	含义	处理方式
400	bad_request	检查请求体 — 可能是无效 model 或格式错误的 messages。
401	unauthenticated	密钥缺失或已吊销。请在控制台创建新密钥。
402	insufficient_balance	余额不足，充值后重试。
429	rate_limited	根据 Retry-After 请求头退避重试。
502/503	upstream_error	已自动重试 — 如持续出现请提交支持工单。

✓

幂等性： 对非幂等请求传递 Idempotency-Key 请求头（UUID）。我们在 24 小时内去重。

SDK

官方 SDK 封装了重试、流式传输和错误规范化。底层是对 HTTP API 的轻量包装。

Python

pip install canalapi

TypeScript

npm i @canalapi/sdk

go get canalapi/canal-go

→

准备好开始构建了吗？

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

获取 API 密钥 →

← 简介对话补全 →