cartesia-api

Cartesia Voice & Speech APIs

Cartesia は、テキスト読み上げ（Sonic）、音声テキスト変換（Ink）、音声（ライブラリ、クローン、ローカライズ）、および関連する HTTPS と WebSocket API を提供しています。このスキルでは、アプリケーションへの統合とエージェントによるコーディング支援を扱います。Cartesia Line（マネージド音声エージェント、cartesia CLI、テレフォニー、Line SDK）については、cartesia-line を使用してください。

基本方針

• HTTPS のみ： すべての HTTP エンドポイントでは https://api.cartesia.ai を使用します。WebSocket では wss:// を使用します
  • HTTP はサポートされていない場合があります。HTTP 経由で使用されたキーは自動的にローテーションされることがあります
• API バージョン： Cartesia の API は日付でバージョン管理されています（Cartesia-Version: YYYY-MM-DD）。サービス全体で単一のバージョンを固定し、バージョンの更新はメジャーな依存関係のアップグレードと同様に扱ってください。新しいバージョンには破壊的変更が含まれることがあるため、実行時や呼び出しごとに変更するのではなく、固定して使用します。
  • SDK を使用する場合（推奨）： SDK には、構築時およびテスト時に使用された Cartesia-Version がすでに固定されています。その管理に任せてください。独自の日付を指定して（たとえば default_headers 経由で）上書きしないでください。SDK が任意のバージョンで動作するとは限りません。新しい API バージョンに移行するには、SDK をアップグレードしてください。
  • API を直接呼び出す場合（SDK なし）： Cartesia-Version を自分で送信する必要があります。ブラウザーの WebSocket ではハンドシェイクヘッダーを設定できないため、?cartesia_version=... として渡してください（両方が指定された場合はクエリが優先されます）。
  • 任意：GET https://api.cartesia.ai/ は {"ok":true,"version":"..."} を返します（ゲートウェイの現在のデフォルト）。新しいクライアントを設定する際に役立ちます。
• サーバー側の認証： Cartesia API キー（sk_car_...）を使って Authorization: Bearer <api_key> を使用します。
• クライアントアプリ（ブラウザー／モバイル）： API キーを埋め込むことは絶対に避けてください。バックエンドで有効期間の短いアクセストークンを発行し、Authorization: Bearer <access_token> を使用します
  • ブラウザーから WebSocket を使用する場合は、トークンを ?access_token=<token> として渡してください（WS ハンドシェイクではヘッダーを使用できません）
  • JS/TS SDK（v3 以降）はアクセストークンを使ってブラウザーで動作します。WebSocket を独自に実装するより、SDK の使用を優先してください（以下のブラウザー用サンプルを参照）。SDK はサーバー専用だと決めつけないでください
  • Access Token API を参照してください
• エラー： Cartesia-Version 2026-03-01 以降では、エラーは構造化 JSON（error_code、title、message、request_id、任意の doc_url）です
  • それ以前のバージョンでは、従来のプレーンテキストまたは従来の JSON 構造が返される場合があります
  • API Errors と API conventions を参照してください
• 信頼できる情報源： SDK、プラグイン、統合機能よりも先に更新されるため、ドキュメントを優先してください
  • ドキュメントを Markdown として取得： docs.cartesia.ai の任意のページに .md を追加すると、エージェントが読み取れる Markdown を取得できます（例：https://docs.cartesia.ai/api-reference/stt/transcribe.md）。拡張子なしの URL は、人間向けの HTML ページです。プログラムからドキュメントを取得する場合は、.md 形式を優先してください
  • 機械可読なインデックスについては、llms.txt と llms-full.txt を参照してください
• 任意の MCP： ホスト型サーバー https://mcp.cartesia.ai/mcp（Playground 経由の OAuth）では、Cursor / Claude で音声の一覧表示、TTS/STT の実行、クローン作成、発音辞書の管理ができます
  • MCP は本番環境で API / SDK の代わりにはなりません
  • ローカルの stdio（uvx cartesia-mcp）は開発用です。MCP docs を参照してください

Sonic によるテキスト読み上げ（音声の生成）

• TTS モデルの選択： 現在のモデル ID、対応言語、機能については、TTS models を参照してください。モデル ID を記憶に頼って決めないでください。トレーニングデータは古くなります（例：sonic-2 は現在のモデルではありません）。
• 音声 ID： 音声 ID を でっち上げないでください。架空の UUID では解決できません。実在する音声 ID は安定しているため、定数としてハードコードするのは問題なく、一般的です。playground または List Voices からコピーしてください。List Voices は音声を 見つけて選ぶ ために使い、リクエストごとに必須の呼び出しとして使わないでください。
• エンドポイントの選択 — バイト列と WebSocket： テキストがあらかじめ決まっている場合（固定文字列、ボタンの押下など）は、POST /tts/bytes を使ってください。生成と同時に音声がストリーミングされ、よりシンプルです。WebSocket を使うのは、入力テキスト が逐次届く場合（例：LLM のトークンストリームをパイプする場合）に限ってください。continuations が該当します。WebSocket をデフォルトで選ばず、TTS endpoints で比較してください。
• 出力音声形式： コンテナー、エンコーディング、サンプルレートについては、TTS output audio format を参照してください（wav + pcm_s16le @ 44.1 kHz は、安全で自己完結したデフォルトです。mp3 には個別の encoding はありません）。

Ink による音声テキスト変換（音声の文字起こし）

• STT モデルの選択： 現在のモデルと対応言語については、STT models を参照してください。
• API エンドポイントの選択： Compare STT Endpoints を参照してください。
• 入力音声： 対応形式については、STT input encodings を参照してください（.wav のような自己完結したファイルには、それ自体のヘッダーが含まれています）。
• STT コードを書く前に： Common STT Pitfalls を読んでください。
  • ドキュメントに基づかずに、モデルや API の動作を推測しないでください。クライアント側のささいなミスが、気づきにくいものの深刻な精度低下を引き起こします。
  • よくあるクライアント側のエラー：
    • 文字起こしテキストの空白を削除したり、挿入したりすること（モデルのテキストをそのまま読み取ってください。.strip() も正規化も行わないでください）。
    • 文字起こしの断片を不適切に連結すること。
    • API 仕様に従わないこと。

Cartesia Python SDK

pip install cartesia

• README.md
• エクスポートされているすべてのリソース
• サンプル
• 非同期処理のサンプル

SDK のバージョンに固有のソースコードを参照するには、/heads/main/ を /tags/vX.X.X/（例：/tags/v3.2.0/）に置き換えてください。

Cartesia TypeScript / JavaScript SDK

npm i @cartesia/cartesia-js

• README.md
• エクスポートされているすべてのリソース
• Node / Bun / Deno のサンプル
• ブラウザーのサンプル

SDK のバージョンに固有のソースコードを参照するには、/heads/main/ を /tags/vX.X.X/（例：/tags/v3.2.0/）に置き換えてください。

どの経路を使うか

目的	経路
REST/WebSocket を呼び出すアプリまたはバックエンド	Python SDK、JS/TS SDK、またはネイティブ API リクエスト／fetch
MCP を使う IDE エージェント	ホスト型の https://mcp.cartesia.ai/mcp ＋ ドキュメントのフォールバック
デプロイ済みの音声エージェント、Line、テレフォニー	cartesia-line
OpenClaw の初期設定	https://cartesia.sh/openclaw.md の後にドキュメント／llms.txt

クイックスタート（HTTP TTS、単発）

形式のみです。使用する Cartesia-Version に応じて、フィールド名と列挙値をAPI リファレンスで確認してください。

curl -X POST "https://api.cartesia.ai/tts/bytes" \
  -H "Authorization: Bearer $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sonic-3",
    "transcript": "Hello from Cartesia.",
    "voice": { "id": "f786b574-daa5-4673-aa0c-cbe3e8534c02" },
    "output_format": {
      "container": "wav",
      "encoding": "pcm_s16le",
      "sample_rate": 44100
    },
    "language": "en"
  }' \
  --output /tmp/out.wav

基本的な考え方（LLM 向け）

• Sonic ＝ 音声を生成するための TTS モデル
• Ink ＝ 音声を書き起こすための STT モデル
• Line ＝ 別の製品です。ご自身の Python エージェントをデプロイし、その周辺の STT／TTS／テレフォニーは Cartesia が実行します。「自分のサーバーから TTS API を呼び出す」方式とは異なります。
• 同時実行数／クォータ： API エラーに従って、429 クラスのエラーと、構造化された concurrency_limited／quota_exceeded を処理してください。

言語、ロケール、アクセントの違い

これらを混同しないでください。

• 言語 — 大まかなコード（en、es）
• ロケール — 言語と地域の区分（en-US、en-GB）
• アクセント — ロケール内の特定の音声 ID

1 つのロケールに複数のアクセントが存在する場合があります。en-US には、一般的なアメリカ英語と南部アメリカ英語が含まれます。国だけでは、アクセントを一意に選べません。クライアントが値を保存したり、再送信したりする場合は、表示名より API のカタログ ID を優先してください。

このリポジトリの関連資料

• Line 音声エージェント： cartesia-line
• リンク集： references/resources.md

よくある間違い

1. SDK の Cartesia-Version を上書きする： SDK を使う場合、バージョンを設定したり上書きしたりしないでください。SDK にはテスト済みのバージョンが固定されています。バージョンを上げるには SDK をアップグレードしてください。日付を指定するのは、生の HTTP／WS 呼び出しのみです。その場合は、すべての箇所で同じ日付を使用してください（日付が誤っていると、気付きにくい不具合やレガシー形式のエラーが発生します）。
2. フロントエンドコードに API キーを置く： バックエンドで発行した有効期間の短いアクセストークンを使用してください。
3. 認証ヘッダーの形式が誤っている： 例では Authorization: Bearer を使用しています。古いスニペットではなく、最新のドキュメントに合わせてください。
4. 記憶に頼って古い SDK／モデルコードを使う： 学習データは API の更新に追いついていません。モデル ID は変更されることがあり（例：sonic-2）、JS SDK の名前付き import { CartesiaClient } は非推奨で、ブラウザーでは動作しません。import Cartesia from "@cartesia/cartesia-js"（またはデフォルトインポート）を使用してください。モデルはモデルのドキュメントで、SDK の使用方法はリンク先の README／例で確認してください。
5. cartesia deploy／Line にこのスキルを使う： cartesia-line に切り替えてください。