Skip to main content
すべてのエンドポイントは HTTPS を使用します。HTTP はサポートされていません。HTTP 経由で API を呼び出した API キーは、自動ローテーションの対象になる場合があります。
すべての API リクエストは次のベース URL を使用します: https://api.cartesia.ai。(WebSocket の場合、対応するプロトコルは wss:// です。)

​
必ず Cartesia-Version ヘッダーを送信する

API に送るリクエストには毎回、統合をテストした日付 (YYYY-MM-DD) を含む Cartesia-Version ヘッダーを付与してください。WebSocket の場合は、代わりに ?cartesia_version クエリパラメーターを使用することもでき、こちらが優先されます。 これにより、Cartesia は廃止予定のお知らせを適時に提供でき、可能な範囲で自動的な後方互換性を提供できます。 特定の Cartesia-Version に対しては、既存の入力および出力フィールドは保持されますが、次のような非破壊的な変更を行うことがあります:
  1. 任意のリクエストフィールドを追加する。
  2. 追加のレスポンスフィールドを追加する。
  3. 特定のエラータイプの条件を変更する。
  4. enum 風の出力値にバリアントを追加する。
Cartesia のバージョニング方式は、Anthropic API を参考にしています。

​
サーバーからリクエストを送信する場合は API キーを使用する

play.cartesia.ai/keys で新しい API キーを作成します。リクエストのヘッダーに Authorization: Bearer <api_key> を含めてください。

​
管理エンドポイントには admin API キーを使用する

一部のルート（クレジット使用量、エージェント使用量、API キーのメタデータなど）では、admin API キー（sk_car_admin_...）が必要です。これらは play.cartesia.ai/keys で作成する API キーとは別物であり、各タイプのキーはそれぞれ専用のルートでのみ動作します。 admin キーは play.cartesia.ai/keys/admin で作成できます（組織管理者のみ）。送信方法は同じです: Authorization: Bearer <admin_api_key>。

​
クライアントアプリからリクエストを送信する場合はアクセストークンを使用する

クライアントアプリでは API キーを決して使用しないでください。これらはアカウントの完全なアクセス権を付与し、ブラウザやモバイルのコードから抽出されてしまう恐れがあります。 代わりに、サーバー側で短命のアクセストークンを生成してクライアントに送信できます。生成方法については Access Token API リファレンス を参照してください。
  • HTTP リクエストの場合は、ヘッダーに Authorization: Bearer <access_token> を含めてください。
  • WebSocket 接続では、ブラウザが WebSocket ハンドシェイクでヘッダーを設定できないため、?access_token=<access_token> クエリパラメータとしてトークンを渡してください。

​
レスポンスコードを確認する

Cartesia の API は標準的な HTTP レスポンスコードを使用します。詳細は httpstatuses.io を参照してください。

​
構造化されたエラーレスポンスをパースする

Cartesia-Version の値が 2026-03-01 以降の場合、Cartesia は構造化された JSON エラーを返します。 すべての現行エラーコード、スキーマ、フィールドの null 許容性を含む完全なエラーリファレンスについては、API エラー を参照してください。
HTTP error response (Cartesia-Version 2026-03-01 and newer)
{
  "error_code": "concurrency_limited",
  "title": "Too many concurrent requests",
  "message": "You have exceeded your plan's concurrency limit.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
フィールドの意味:
  1. error_code: クライアント側のロジックで利用できる機械可読な識別子。null の場合があります。
  2. title: 短い人間可読のサマリー。
  3. message: 人間可読の詳細な説明。
  4. request_id: サポート/デバッグ用のリクエスト識別子。
  5. doc_url: 該当エラーに関するドキュメントへの任意のリンク (利用可能な場合)。
現在よく使われる error_code の値には、quota_exceeded、concurrency_limited、voice_model_mismatch、voice_not_found、model_not_found、language_not_supported、file_too_large、unsupported_audio_format、plan_upgrade_required などがあります。 WebSocket および SSE のエラーイベントには、同じエラーフィールドに加えてトランスポートのコンテキスト情報が含まれます:
WebSocket/SSE error event (Cartesia-Version 2026-03-01 and newer)
{
  "type": "error",
  "done": true,
  "status_code": 429,
  "error_code": "concurrency_limited",
  "title": "Too many concurrent requests",
  "message": "You have exceeded your plan's concurrency limit.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000:happy-monkeys-fly:8a0f5f3a-3b2f-4f28-b73e-8c5f27e2f8bb",
  "context_id": "happy-monkeys-fly"
}
注意点:
  1. context_id は、TTS WebSocket のエラーで利用可能な場合に含まれます。
  2. status_code は WebSocket/SSE のエラー ペイロードに含まれます。HTTP の場合、ステータスは引き続き HTTP レスポンスのステータス行に含まれます。
  3. request_id は常に文字列です。HTTP と SSE のリクエスト ID は UUID ですが、WebSocket のリクエスト ID には追加のコンテキストが含まれる場合があります。
Cartesia-Version の値が 2026-03-01 より前の場合 (および無効なバージョンの場合) は、代わりにレガシーのエラー形式が返されます:
  1. HTTP エラーは Title: Message 形式のプレーンテキストです。
  2. WebSocket/SSE のエラーは文字列のみのエラーメッセージを持つレガシーエンベロープを使用します。

​
メソッドに応じてデータを渡す

すべての GET リクエストでは、データをクエリパラメーターで渡します。すべての POST リクエストでは、JSON ボディまたは multipart/form-data を使用します。