> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API の規約
すべてのエンドポイントは 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](https://docs.anthropic.com/en/api/versioning) を参考にしています。
### サーバーからリクエストを送信する場合は API キーを使用する
[play.cartesia.ai/keys](https://play.cartesia.ai/keys) で新しい API キーを作成します。リクエストのヘッダーに `Authorization: Bearer ` を含めてください。
### 管理エンドポイントには admin API キーを使用する
一部のルート（[クレジット使用量](/api-reference/usage/credits)、[エージェント使用量](/api-reference/usage/agents)、[API キーのメタデータ](/api-reference/api-keys/list)など）では、**admin** API キー（`sk_car_admin_...`）が必要です。これらは [play.cartesia.ai/keys](https://play.cartesia.ai/keys) で作成する API キーとは別物であり、各タイプのキーはそれぞれ専用のルートでのみ動作します。
admin キーは [play.cartesia.ai/keys/admin](https://play.cartesia.ai/keys/admin) で作成できます（組織管理者のみ）。送信方法は同じです: `Authorization: Bearer `。
### クライアントアプリからリクエストを送信する場合はアクセストークンを使用する
クライアントアプリでは API キーを決して使用しないでください。これらはアカウントの完全なアクセス権を付与し、ブラウザやモバイルのコードから抽出されてしまう恐れがあります。
代わりに、サーバー側で短命のアクセストークンを生成してクライアントに送信できます。生成方法については [Access Token API リファレンス](/api-reference/auth/access-token) を参照してください。
* HTTP リクエストの場合は、ヘッダーに `Authorization: Bearer ` を含めてください。
* WebSocket 接続では、ブラウザが WebSocket ハンドシェイクでヘッダーを設定できないため、`?access_token=` クエリパラメータとしてトークンを渡してください。
### レスポンスコードを確認する
Cartesia の API は標準的な HTTP レスポンスコードを使用します。詳細は [httpstatuses.io](https://httpstatuses.io) を参照してください。
### 構造化されたエラーレスポンスをパースする
`Cartesia-Version` の値が `2026-03-01` 以降の場合、Cartesia は構造化された JSON エラーを返します。
すべての現行エラーコード、スキーマ、フィールドの null 許容性を含む完全なエラーリファレンスについては、[API エラー](/use-the-api/api-errors) を参照してください。
```json HTTP error response (Cartesia-Version 2026-03-01 and newer) theme={null}
{
"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 のエラーイベントには、同じエラーフィールドに加えてトランスポートのコンテキスト情報が含まれます:
```json WebSocket/SSE error event (Cartesia-Version 2026-03-01 and newer) theme={null}
{
"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` を使用します。