CanalAPI
Getting started

はじめに

CanalAPIは600以上のLLM・画像・音声モデルを統合したゲートウェイです。OpenAI互換クライアントを使い、base_urlをhttps://api.canalapi.com/v1に向けてキーを渡すだけで利用できます。

60秒で始められます
コンソールでキーを取得し、以下のスニペットを実行するだけで完了です。
APIキーを取得 →
→ チャット補完
GPT-4o、Claude 4、Gemini 2.5 — 同じ形式
→ Embeddings
OpenAI & BGEベクトル、8K+コンテキスト
→ 自動ルーティング
チャネル間の自動フェイルオーバー
→ ストリーミング
SSE、トークン単位、OpenAI互換

クイックスタート

必要なものは2つだけ：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 ... ヘッダーでキーを渡してください。キーはスコープ付き — コンソールで環境ごと（開発/ステージング/本番）にキーを作成できます。

i
ヒント： 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任意booleantrueの場合、SSEでトークンをストリーム返却。デフォルト：false。
temperature任意number0〜2。高いほど多様な出力。デフォルト：1。
max_tokens任意integer補完トークン数の上限。モデル依存のデフォルト値。
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エラーが発生した場合は自動的に正常なチャネルへリトライ — ルーティングプールが枯渇した場合のみエラーが返されます。

コード意味対処法
400bad_requestリクエストボディを確認 — 無効なmodelまたは不正なmessages形式の可能性があります。
401unauthenticatedキーがないか失効しています。コンソールで新しいキーを作成してください。
402insufficient_balance残高不足。チャージして再試行してください。
429rate_limitedRetry-Afterヘッダーに従ってバックオフしてください。
502/503upstream_error自動リトライ済み — 継続する場合はサポートチケットを送ってください。
✓
べき等性： 非べき等リクエストにはIdempotency-Keyヘッダー（UUID）を渡してください。24時間以内に重複排除されます。

SDK

公式SDKはリトライ、ストリーミング、エラー正規化をラップします。内部ではHTTP APIの薄いラッパーです。

Python
pip install canalapi
TypeScript
npm i @canalapi/sdk
Go
go get canalapi/canal-go
→
構築を始める準備はできましたか？
最初のAPIキーを取得して、2分以内にリクエストを送りましょう。
APIキーを取得 →
← はじめにチャット補完 →