# 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 <key>（OpenAI / 汎用スタイル）と x-api-key: <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	モデルスラッグ。/v1/modelsを呼ぶか料金ページで最新の利用可能モデルを確認できます。
messages必須	array	{ role, content }オブジェクトの配列。ロールはsystem、user、assistantをサポート。
stream任意	boolean	trueの場合、SSEでトークンをストリーム返却。デフォルト：false。
temperature任意	number	0〜2。高いほど多様な出力。デフォルト値はモデル依存。
max_tokens任意	integer	補完トークン数の上限。デフォルト値はモデル依存。
tools任意	array	Function Calling用のツール定義。リクエストスキーマは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/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は標準フィールドをすべて転送します。

ネイティブGeminiPOST/v1beta/models/*:generateContent

OpenAI互換の /v1 に加え、CanalAPIは /v1beta でネイティブのGeminiインターフェースを公開しています。Gemini SDK（@google/generative-ai）のbase_urlをhttps://api.canalapi.com/v1betaに向け、CanalAPIキーで認証するだけで、generateContentとstreamGenerateContentをコード変更なしに利用できます。

認証： 2種類のヘッダーに対応し、いずれも等価です：Authorization: Bearer <key> と x-goog-api-key: <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、1ファイル ≤ 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"

対応形式： image と mask は image/jpeg、image/png、image/webp のみ対応し、1ファイル25MBまでです。

エラーとリトライ

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 で利用可能。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キーを取得して、2分以内にリクエストを送りましょう。

APIキーを取得 →

← はじめにチャット補完 →