mcpField
C
cartesia-sonic

cartesia-sonic

github.com/calesthioクリエイティブ・メディア219103 回インストール15 週間前に更新
リポジトリ

cartesia-sonic について

Cartesia Sonic のテキスト読み上げを選定、指示、統合、レビューするメディア制作エージェント向けスキルです。Sonic TTS と Cartesia の他の音声 API を区別し、エンドポイント選択や制作上の指針を示します。

主な機能

  1. 01Sonic TTS の機能とモデル選択
  2. 02音声とボイスクローニングの選択肢
  3. 03音声ローカライズと変換の指針
  4. 04用途に応じた API エンドポイント選択
  5. 05原稿と発音のガイダンス

活用シーン

  1. 01リアルタイム音声エージェント用の音声生成
  2. 02ナレーションや通知音声の一括制作
  3. 03吹き替えやローカライズ手法の選定
  4. 04Cartesia Sonic 統合設定のレビュー

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/calesthio/generative-media-skills --skill cartesia-sonic

インストール後、Claude Code で/cartesia-sonicを入力して読み込まれたか確認します。

同梱ファイルEVAL.md

詳細

Cartesia Sonic 本番運用スキル

メディア制作エージェントが音声出力に Cartesia Sonic を選択、プロンプト設定、統合、または評価する場合に、このスキルを使用してください。まず Sonic を低遅延のテキスト読み上げプロバイダーとして扱い、本番環境で明確に必要な場合に限り、Cartesia の関連音声 API を使用してください。

以下の変動する情報は、2026-07-10 に Cartesia の公式ドキュメントまたは法務関連ページで確認済みです。予算、コンプライアンスに関する主張、モデル ID、料金、同時実行数、対応言語、または API の動作を確定する前に、再確認してください。

プロバイダーの範囲

確認済みの情報：

  • Sonic は Cartesia のテキスト読み上げモデルファミリーです。現在の本番環境でのデフォルトは sonic-3.5 です。API リファレンスには sonic-3 と sonic-latest も記載されています。
  • Sonic はテキストを受け取り、生成された音声を返します。会話型音声エージェント、ナレーション、吹き替え、アバター、通知、広告、ローカライゼーションなど、ワークフローがトランスクリプトから始まる用途に適しています。
  • Cartesia は、音声認識用の Ink、ホスト型音声エージェント用の Line、音声クローン、音声ローカライゼーション、インフィル、ボイスチェンジャーもドキュメント化しています。これらすべてを「Sonic TTS」として紹介しないでください。使用する Cartesia の具体的な機能を明記してください。
  • ボイスチェンジャーは TTS ではありません。入力された音声クリップを受け取り、同じイントネーションで別のターゲット音声に変換した音声を返します。
  • 音声間変換またはボイスコンバージョンに関する主張は、Cartesia のドキュメントで別の対応経路が明示的に追加されない限り、ドキュメント化されている voice-changer エンドポイントに限定してください。

本番環境での指針：

  • オフラインのローカルレンダリングや最大限のポストプロダクション編集性よりも、最初のバイトが届くまでの時間の短さ、会話に適したペース、多言語音声、API ストリーミングが重要な場合は、Cartesia Sonic を優先してください。
  • エアギャップ環境での処理、ネットワークに依存しない予測可能なレンダリング、または Cartesia の現在のアカウント設定では満たせないライセンス／セキュリティ要件があるプロジェクトでは、リアルタイム性のないバッチ TTS プロバイダーまたはローカル TTS を優先してください。
  • メディアパイプラインでは、選択したエンドポイント、モデル ID、音声 ID、言語、出力形式、Cartesia-Version、generation_config、発音辞書 ID、ソーストランスクリプトのチェックサムをアセットマニフェストに記録してください。

機能マップ

Sonic テキスト読み上げ

確認済みの情報：

  • sonic-3.5 は、Cartesia が最速かつ最も自然な TTS モデルとして紹介しており、90 ミリ秒未満のレイテンシと、42 言語のネイティブサポートを備えています。
  • このモデルは、トランスクリプトに忠実に従い、注文番号や ID などの英数字を自然に処理し、文脈を考慮して英語の同形異音異義語を発音すると説明されています。
  • 2026 年の変更履歴では、Sonic 3.5 は一般提供済みで、本番環境に対応しているとされています。旧 Sonic モデルと複数のスナップショット／言語は、2026-06-01 に提供終了となりました。

本番環境での指針：

  • 新規の本番環境では、旧 sonic、sonic-english、sonic-multilingual、sonic-2、sonic-turbo ではなく、sonic-3.5 から始めてください。
  • sonic-3 は、回帰テストとの互換性が必要な場合、または特定の音声／制御経路で検証済みの場合に限って使用してください。
  • プロジェクトがモデルの自動変更を明示的に求めていない限り、編集／レンダリングを固定するパイプラインでは sonic-latest への固定を避けてください。最新の安定スナップショットには sonic-3.5 を使用し、完全な再現性が必要な場合は日付付きの sonic-3.5-YYYY-MM-DD スナップショットを使用してください。
ボイス

文書化されている事実：

  • Cartesia は、500 種類以上の標準搭載ボイスとカスタムボイスを提供しています。
  • TTS リクエストでは、ID を指定してボイスを選択できます。
  • Cartesia のボイスガイダンスでは、本番環境の音声エージェントには安定したボイスを、AI キャラクターにはより感情豊かなボイスを使い分けています。
  • インスタントボイスクローンはプレイグラウンドと API で利用できます。アップロードまたは録音した最大 10 秒の音声クリップを使用します。インスタントクローンのトレーニングは高速かつ無料とされています。
  • プロフェッショナルボイスクローン（PVC）は、Startup ティア以上で利用できます。より多くの音声データを用いたファインチューニングを行います。Cartesia の文書では、最低 30 分、品質と作業量のバランスを高めるには 2 時間を推奨しています。
  • PVC のトレーニングには約 3 時間かかるとされています。プレイグラウンドでのステータスには Draft／Failed／Training／Completed があり、API のファインチューニング状態には created、training、completed、failed があります。
  • PVC はファインチューニングに使用したベースモデルに固定されます。将来のベースモデルを使用するには再トレーニングが必要で、別途ファインチューニング費用が発生します。
  • 2026 年の変更履歴によると、プロフェッショナルボイスクローンが Sonic 3.5 で利用可能になりました。

本番環境でのヒューリスティック：

  • ナレーションや広告で、権利処理済みのタレント音声がない場合は、クローンを作成する前に複数の標準ボイスを試聴してください。クローンの作成には、権利、管理、保持に関する義務が伴います。
  • 対話型エージェントでは、感情表現の強いボイスを試す前に、安定感やリアリティのあるボイスをテストしてください。10 秒のデモではドラマチックに聞こえるボイスでも、長時間の通話では疲れやすかったり、聞き取りにくかったりすることがあります。
  • キャラクター、ゲーム、コンパニオン向けの制作では、実際のスクリプトを使って感情豊かなボイスと感情コントロールを試聴してください。感情表現の指示への反応は、ボイスによって異なります。
  • ブランドボイスクローンは、ライセンスを受けたタレント素材として扱ってください。同意、許可された用途、地域、期間、取り消しのルール、開示要件をプロジェクトと併せて保管してください。
ボイスのローカライズ

文書化されている事実：

  • Cartesia は、ボイスを新しい言語やアクセントでネイティブに聞こえるようにするボイスのローカライズについて説明しています。
  • 料金の文書では、ボイスのローカライズは 1 回限りの 225 クレジットとされています。

本番環境でのヒューリスティック：

  • 同じ承認済みの話者の声を複数の言語で維持する必要がある場合は、ローカライズを使用してください。
  • ローカライズによって、翻訳、文化的な適応、スクリプトのタイミング、リップシンク、タレントの法的な同意まで解決できるとは考えないでください。これらは別個の制作タスクとして対応してください。
  • 発音、アクセントの適切さ、明瞭さ、ブランドとの適合性について、ネイティブのレビュアーと一緒にローカライズしたボイスを QA してください。
ボイスチェンジャー

文書化されている事実：

  • voice-changer/bytes および voice-changer/sse エンドポイントは、音声ファイルを入力として受け取り、イントネーションはそのままに別のボイスに変換した音声を返します。
  • 入力音声形式には、FLAC、MP3／MPEG／MPGA、OGA／OGG、WAV、WEBM など、一般的なコンテナ形式が含まれます。
  • 出力コンテナ形式には raw、wav、mp3 があり、サンプルレートには 8000、16000、22050、24000、44100、48000 Hz があります。
  • ボイスチェンジャーの料金は、入力音声 1 秒あたり 15 クレジットです。

本番環境でのヒューリスティック：

  • テキストからの再構成よりも、タイミング、イントネーション、演技を維持することが重要な場合は、すでに収録された音声のボイス変換にボイスチェンジャーを使用してください。
  • 単語を正確に制御したい場合、発音辞書を使いたい場合、差し替え音声をきれいに収録したい場合、または翻訳・ローカライズ済みの原稿を使いたい場合は、トランスクリプトから TTS を使用してください。
  • 吹き替えでは、翻訳済みスクリプトからの TTS、ガイド音声を使ったボイスチェンジャー、または両者の組み合わせのいずれを使うか、明確に決めてください。別の方法に黙って置き換えないでください。

エンドポイントの選択

ドキュメントに記載されている事実：

  • POST /tts/bytes：全文が確定しており、1 回の HTTP リクエストでストリーミング音声バイト列を生成する必要がある場合に最適です。バッチジョブ、キャッシュファイル、通知、ナレーションのセグメント、ファイルのエクスポートに効率的です。
  • POST /tts/sse：全文が確定しており、WebSocket を使わずにタイムスタンプが必要な場合、またはスタックがすでに Server-Sent Events を消費している場合に最適です。音声チャンクは JSON/base64 の SSE イベントとして送信されます。
  • WSS /tts/websocket：長時間のセッション、LLM から逐次届くテキスト、多数のターンにわたる低レイテンシ、タイムスタンプ、1 つのソケットでの複数の発話に最適です。
  • Bytes と SSE では、リクエストごとに全文が必要です。SSE の context_id はログ用にエコーバックされますが、複数の HTTP リクエストを 1 つの発話にまとめることはありません。
  • WebSocket はコンテキストと継続をサポートします。1 つの発話には同じ context_id を再利用し、部分テキストは continue: true を指定して送信し、continue: false で確定します。
  • コンテキストは最後の音声出力のストリーミングから 1 秒後に自動的に期限切れになります。期限切れのコンテキストに別の入力を送信することはサポートされていません。

選択の目安：

  • ナレーション、広告、解説動画のナレーション、アプリ内通知、バッチローカライズ、キャッシュ可能なプロンプトなど、ファイルを生成する場合は bytes を使用します。
  • WebSocket を使えないものの、単語や音素のタイミング情報が必要なファイルを生成する場合は sse を使用します。
  • ライブエージェント、LLM トークンのストリーミング、割り込み対応のエクスペリエンス、または全文を一度に用意できない場合は websocket を使用します。

失敗につながるケース：

  • LLM の断片を別々の HTTP リクエストとして送信すると、プロソディの継ぎ目が生じます。1 つの発話には WebSocket の継続を使用してください。
  • スペースや句読点を含めずにコンテキストを分割すると、テキストがそのまま連結され、つなぎ合わせたチャンクの発音を誤ることがあります。
  • 1 つの WebSocket コンテキスト内でモデル、音声、言語、出力形式、生成設定を変更すると、コンテキスト内で変更できるのは transcript、continue、duration のみという、ドキュメントに記載された入力形式のルールに違反します。
  • アイドル状態の WebSocket を開いたままにすると、WebSocket の上限に達し、429 エラーが発生することがあります。

主なリクエストフィールド

ドキュメントに記載されている事実：

  • TTS リクエストには model_id、transcript、voice、output_format が必要です。
  • 言語フィールドは、選択した音声でどの言語を話すかを指定します。利用可能な言語はモデルによって異なる場合があります。
  • TTS は SSE で単語と音素のタイムスタンプをサポートしています。WebSocket もタイムスタンプの用途に対応しています。Bytes は音声のみです。
  • 発音辞書は、pronunciation_dict_id を使って sonic-3 モデルおよびそれ以降のモデルでサポートされています。
  • generation_config は sonic-3 と sonic-3.5 で利用できます。
  • 以前のトップレベルの speed 列挙型は非推奨です。代わりに generation_config.speed を使用してください。
  • API リクエストには、統合をテストした日付を Cartesia-Version として指定してください。WebSocket では、クエリパラメーターとして cartesia_version を渡せます。

本番環境でのデフォルト：

{
  "model_id": "sonic-3.5",
  "voice": { "mode": "id", "id": "VOICE_ID_APPROVED_FOR_THIS_PROJECT" },
  "language": "en",
  "output_format": {
    "container": "wav",
    "encoding": "pcm_s16le",
    "sample_rate": 48000
  },
  "generation_config": {
    "speed": 1.0,
    "volume": 1.0
  }
}

ヒューリスティック：

  • 対象のパイプラインで別のサンプルレートが必要でない限り、動画制作のマスターには WAV／48 kHz を使用します。
  • 編集時の余裕よりファイルサイズの小ささを優先する配信用プレビューやアセットには、MP3 のみを使用します。
  • リアルタイムプレーヤー、電話システム、ストリーミングスタックで必要とされ、後続処理のエンコード形式とサンプルレートの要件が明確な場合にのみ、raw PCM を使用します。
  • 電話用途では、高レートの音声を生成して何度もトランスコードするのではなく、後続処理のコーデックやサンプルレートに合わせます。

Sonic のトランスクリプト作成

文書化されている事実：

  • Sonic 3.5 は、プロンプトエンジニアリングを最小限に抑えた、自然で適切な句読点を使ったトランスクリプトテキストで動作するように設計されています。
  • Cartesia は、完全なフレーズと文末の句読点を推奨しています。
  • Sonic は、数字、通貨、日付、電話番号、住所、メールアドレス、一般的な略語、頭字語について、一般的な表記形式に対応しています。
  • 過度な前処理、句読点の除去、大文字・小文字の強制は、出力品質を損なう可能性があります。
  • すべて大文字のテキストは頭字語として解釈される場合があります。トークンを一文字ずつ読み上げる場合を除き、通常の大文字・小文字表記を使用してください。
  • 英数字のコードや、文字を一つずつ正確に読み上げる場合は、<spell>...</spell> の使用が推奨されています。
  • break タグで固定のポーズを挿入できますが、break タグを繰り返したり連結したりすると、自然さが損なわれ、エラーが発生する場合があります。

本番環境でのヒューリスティクス：

  • トランスクリプトはプロンプトではなく、演技用の台本として扱ってください。モデルへのメモではなく、読み上げる内容を書いてください。
  • 広告やソーシャル動画の読み上げ用トランスクリプトでは、記号を読み上げる意図がある場合を除き、Markdown、箇条書き、見出し、絵文字、生の JSON、アスタリスク、ハッシュタグは避けてください。
  • タイミングに関するメモは、統合側で保持される有効な SSML／Sonic タグでない限り、トランスクリプトの外に置いてください。
  • 広告やソーシャル動画では、意図的に句読点を使った短い文を書いてください。長すぎる台本を速度調整で修正しようとしないでください。
  • 音声エージェントでは、上流の LLM 出力を、通常の文章、文末の句読点、Markdown なし、未対応の記号なしに制限し、コードには明示的な <spell> タグを使用してください。

発音、言語、アクセントの制御

文書化されている事実：

  • 発音辞書は検索置換ルールであり、一致する単語やフレーズを別の文字列で発音するよう Sonic に指示します。
  • 辞書の発音表記には、IPA に似た Cartesia 構文や、「〜のように聞こえる」というガイダンスを使用できます。
  • 辞書を作成したら、TTS API でその ID を pronunciation_dict_id として渡します。
  • Sonic 3.5 は 42 言語に対応しています。API ドキュメントには、en、fr、de、es、pt、zh、ja、hi、it、ko、nl、pl、ru、sv、tr、tl、bg、ro、ar、cs、el、fi、hr、ms、sk、da、ta、uk、hu、no、vi、bn、th、he、ka、id、te、gu、kn、ml、mr、pa などの言語コードが記載されています。

本番環境でのヒューリスティクス：

  • ブランド名、製品名、医療・法律用語、専門用語、地域の地名、重要な同綴異音語には辞書を使用してください。
  • プロジェクトごとに発音表を管理し、テスト済みの項目だけを Cartesia の発音辞書に登録してください。
  • 考えられるすべての単語を辞書に詰め込まないでください。過度に限定的な置換は不自然な読み上げにつながったり、文脈とうまく噛み合わなかったりする可能性があります。
  • 多言語で出力する場合は、主要言語またはローカライズ対象の言語に合った音声を選んでください。ローカライズと品質確認を行わずに、英語の音声がすべての言語で同じようにネイティブらしく話すと思い込まないでください。

速度、音量、感情、非言語的な表現

確認されている事実：

  • Sonic は、プレイグラウンド、generation_config、または SSML タグを通じて、速度、音量、感情を調整できます。
  • generation_config.speed の範囲は 0.6～1.5 です。
  • generation_config.volume の範囲は 0.5～2.0 です。
  • 感情の調整機能はベータ版として提供されています。Cartesia は、これらを厳密な制御ではなく、指針として説明しています。
  • 感情の方向付けは、その感情がトランスクリプトと一貫している場合に最も効果を発揮します。
  • Sonic は、音声やコンテンツに応じて、非言語的な表現や感情豊かなテキストに反応できますが、本番環境での信頼性はテストする必要があります。

本番環境でのヒューリスティック：

  • まず句読点、台本の文言、音声を活用し、速度／音量／感情の調整は仕上げとして使います。
  • 感情の調整機能は音声ごとにテストします。受け入れられた値と採用されなかったテイクを記録し、同じ感情を表す単語が音声によって同じように機能すると思い込まないでください。
  • ミキシングの代わりに音量調整を使うことは避けます。動画の納品物では、ポストプロダクションで音量を正規化してミキシングしてください。
  • 広告では、「warm」「confident」「urgent」「smiling」の読み上げをそれぞれ別のテイクとして作成し、ラベルに頼らず、実際に聴いて選びます。
  • コンプライアンスやカスタマーサポートの音声エージェントでは、誇張した感情を避け、プロソディを安定させます。

料金、クォータ、スループットの計画

確認されている事実：

  • Cartesia はモデルの使用量をクレジットで計測します。エラーが発生してもクレジットは消費されません。
  • 標準的な TTS の料金は、文字あたり約 1 クレジットです。トランスクリプトの前処理によって多少変動します。
  • Pro Voice Clone を使った TTS の料金は、文字あたり約 1.5 クレジットです。Instant Voice Clone は標準的な TTS と同じ料金で請求されます。
  • Pro Voice Clone のファインチューニングは、トレーニングが成功すると 1,000,000 クレジットかかります。
  • ボイスチェンジャーの料金は、入力音声 1 秒あたり 15 クレジットです。
  • TTS のプランごとの同時実行数の上限は、Free が 2、Pro が 3、Startup が 5、Scale が 15、Enterprise がカスタムと記載されています。
  • WebSocket 接続数の上限は、TTS の同時実行数の上限の 10 倍です。
  • TTS の同時実行数は、アクティブなコンテキストの数で計測されます。HTTP ではリクエストごとに 1 つのコンテキスト、WebSocket では一意の context_id ごとに 1 つのコンテキストとして扱われます。
  • TTS の同時実行数または WebSocket の上限を超えると、429 エラーが返されます。
  • アイドル状態の TTS WebSocket は 5 分後に切断されます。

コストのヒューリスティック：

  • 最終トランスクリプトの文字数から、生成前に必要なクレジットを見積もります。
  • 長いナレーションは編集しやすいようにシーン／段落ごとに分割しますが、同時実行数を守りながら、キューを通じてまとめて処理します。
  • WebSocket を使うエージェントでは、接続をプールし、アイドル状態のソケットを閉じます。開いているソケットの数だけでなく、アクティブな発話コンテキストの数を数えます。
  • PVC の作業では、トレーニングが成功すると固定費として多くのクレジットがかかるため、ファインチューニングを始める前にユーザーの明示的な承認を得ます。

プライバシー、セキュリティ、権利、開示

文書化されている事実：

  • サーバー側の統合では、信頼できる環境の API キーを使用してください。ブラウザーやモバイルのクライアントでは、API キーを埋め込まず、有効期間の短いアクセストークンを使用してください。
  • 使用状況や API キーのメタデータなどの管理エンドポイントには、管理者用 API キーが必要です。
  • TTS および STT の推論では、Enterprise のお客様向けに Zero Data Retention（ZDR）が利用できます。
  • ZDR では、TTS のテキスト入力と音声出力は保持されないと文書化されています。一方で、リクエスト ID、使用量の合計、アカウント情報、サービスの稼働状況データなどの運用メタデータは保持される場合があります。
  • ZDR は、ボイスクローニング、PVC、音声の作成、およびお客様が提供したソース素材を保持する必要があるか、別の方法で処理する必要があるワークフローには適用されません。
  • Cartesia の利用規定では、他者や他社になりすますことを禁止しており、ユーザーが提出できるのは、自身の音声録音、または明示的な同意と必要な権利を得た他者の音声録音のみとしています。

本番環境での要件：

  • 文書化された同意と権利がない限り、人物、有名人、従業員、顧客、ブランドの声を複製、ローカライズ、または声質変更しないでください。
  • ZDR がクローニング用データセットや音声作成用のソース素材にも適用されると示唆しないでください。
  • API キーをクライアントアプリ、生成動画、ログ、スクリーンショット、プロジェクト成果物に含めないでください。
  • 公開向けメディアで合成音声やクローン音声を使用する場合は、プロジェクトの開示方針と適用法に従ってください。少なくとも、声のアイデンティティが視聴者の信頼に影響する可能性がある場合は、制作台帳で該当素材に AI 生成またはクローン音声のラベルを付けてください。
  • 規制対象のコンテンツや機密性の高いコンテンツでは、実際のコンテンツを送信する前に、アカウント所有者と Enterprise/ZDR、DPA/BAA/コンプライアンス要件、リージョン／デプロイのニーズ、保持に関する想定を確認してください。

成果物の管理

生成または変換したすべての音声素材について、次の情報を保存してください。

  • トランスクリプトのテキストまたはチェックサム；
  • モデル ID と Cartesia-Version；
  • エンドポイント（tts/bytes、tts/sse、tts/websocket、voice-changer/bytes など）；
  • 音声 ID、音声ソースの分類（ストック、インスタントクローン、PVC、ローカライズ済み）、権利／同意に関する参照情報；
  • 言語コードと発音辞書 ID／バージョン；
  • 使用した generation_config と SSML／タグ；
  • 出力フォーマットのコンテナ、エンコーディング、サンプルレート、ビットレート；
  • 利用量の見積もりと、入手可能な場合は実際のクレジット数；
  • 安全に保持できる場合は、リクエスト ID またはコンテキスト ID；
  • 人による QA のステータスとメモ；
  • 合成音声／クローン音声の開示が必要な場合は、開示ラベル。

制作契約で明示的に許可されていない限り、ボイスクローニングの元となる録音をプロジェクトフォルダーに保存しないでください。アクセスログと削除ポリシーを備えた管理されたアセットストアを優先してください。

本番環境での QA

承認済みのテイクをすべて聴いて確認してください。波形の確認だけでは不十分です。

確認項目：

  • 文字起こしの忠実度：単語の欠落、挿入、繰り返し、幻覚がないこと。
  • 発音：名前、頭字語、数字、コード、製品用語、住所、金額、日付。
  • 言語／アクセント：ローカライズされた出力はネイティブレビュアーが確認すること。
  • パフォーマンス：長時間の読み上げにおける速度、間、感情、強調、疲労。
  • 技術的品質：クリック音、歪み、クリッピング、ノイズ、不自然な無音、サンプルレートの不一致。
  • 編集しやすさ：カット位置のハンドル、音量の一貫性、シーン単位の分離。
  • 同期：単語／音素のタイムスタンプが、字幕、アバター／リップシンク、または UI イベントと一致していること。
  • 権利：音声の出所と使用許諾が最終成果物に適合していること。
  • 安全性／開示：クローン音声または合成音声のラベルとポリシー要件が満たされていること。

よくある修正方法：

  • 発音の誤り：発音辞書を追加または修正する。フレーズを自然な表現に書き換える。文脈を保ちながら、より短い文でテストする。
  • 読み上げが速すぎる：まずスクリプトを短くし、その後 generation_config.speed を 1.0 未満にしてテストする。
  • 抑揚がない：より表現力豊かな音声を試す。テキストに合った感情の指示を追加する。句読点や表現を見直す。
  • 大げさな読み上げ：感情タグを削除し、安定した音声を選び、句読点を簡素化する。
  • ライブ出力で抑揚につなぎ目が生じる：発話ごとに 1 つのコンテキストを使用する WebSocket の継続方式に切り替える。
  • タイムスタンプがない：SSE または WebSocket を使用してタイムスタンプをリクエストする。タイムスタンプに依存するワークフローでは bytes を使用しない。
  • 同時実行エラー：リクエストをキューに入れ、並列コンテキストを減らし、アイドル状態の WebSocket を閉じるか、プランをアップグレードする。

完全な例

例：90 秒の製品紹介動画向けバッチナレーション

制作の目的：製品動画用に、編集しやすいシーン別ナレーションファイルを作成します。

ワークフロー：

  1. シーンごとにスクリプトを確定します。各行を、文末の句読点を含む完全な文にします。
  2. 対象言語で最初の 2 シーンを使い、ストック音声を 3 種類試聴します。
  3. 文字起こしが完成しており、出力をファイルとして編集するため、POST /tts/bytes を選択します。
  4. シーンごとに 48 kHz の WAV ファイルを 1 つ生成します。
  5. アセットマニフェストに、モデル、音声、言語、出力形式、文字起こしのチェックサム、リクエスト ID を保存します。
  6. 最終スクリプトと照らし合わせて、すべての行を QA します。

リクエスト本文の例：

{
  "model_id": "sonic-3.5",
  "transcript": "Meet Acme Lens, the field camera that tags every inspection before your team leaves the site.",
  "voice": { "mode": "id", "id": "APPROVED_STOCK_VOICE_ID" },
  "language": "en",
  "output_format": {
    "container": "wav",
    "encoding": "pcm_s16le",
    "sample_rate": 48000
  },
  "generation_config": {
    "speed": 0.96,
    "volume": 1.0,
    "emotion": "confident"
  }
}

期待される結果：自然な製品発表のペースで読み上げられ、Markdown や読み上げ用ではない制作メモを含まない、クリーンなナレーションファイルが 1 つ生成されます。

失敗例：

  • ショットに対して行が長すぎる：速度を無理に上げるのではなく、コピーを短くします。
  • ブランド名が間違っている：発音辞書を追加し、影響を受ける行だけを再生成します。
  • 感情表現が大げさに聞こえる：感情設定を削除し、音声の選択と句読点で調整します。

バリエーション：

  • アプリの軽量なプレビューには MP3 を使用します。
  • 同じ行を単語単位のキネティック字幕に使う必要がある場合は、SSE を使用します。
  • PVC は権利とコストの承認後にのみ使用します。
例：リアルタイム LLM 音声エージェント

制作の目的：LLM がトークンをストリーミングするのに合わせて、アシスタントの応答を読み上げます。

ワークフロー：

  1. LLM が Markdown、箇条書き、絵文字を含まず、文末の句読点を備えた、読み上げ可能なプレーンテキストを出力するよう設定します。
  2. ワーカー／セッションプールごとに Cartesia WebSocket を 1 つ開きます。
  3. アシスタントのターンごとに、1 つの context_id を作成します。
  4. continue: true を指定してチャンクを送信し、continue: false でターンを終了します。
  5. コンテキスト内では、音声／モデル／言語／出力設定を同一に保ちます。
  6. アイドル状態のソケットを閉じるか、一定のアイドル期間後に再利用します。

チャンクシーケンスの例：

{
  "model_id": "sonic-3.5",
  "transcript": "I found three available appointment times: ",
  "voice": { "mode": "id", "id": "APPROVED_AGENT_VOICE_ID" },
  "language": "en",
  "context_id": "turn-8472",
  "continue": true,
  "output_format": {
    "container": "raw",
    "encoding": "pcm_f32le",
    "sample_rate": 44100
  }
}

{
  "transcript": "Monday at 9:30 AM, Tuesday at 2:00 PM, or Thursday at 11:15 AM.",
  "context_id": "turn-8472",
  "continue": false
}

期待される結果：2 つのチャンク間で安定した抑揚を保った、途切れのない 1 つの発話が生成されます。

失敗例：

  • 最初のチャンクの後にスペースがないと、単語がつながってしまいます。
  • 有効期限が切れた後に同じコンテキストを再利用することはサポートされていません。
  • アイドル状態のソケットを開きすぎると、429 エラーが発生します。

バリエーション：

  • 確認コードには <spell> タグを使用します。
  • 音声を電話通話に直接ストリーミングする場合は、テレフォニー用のサンプルレート／エンコーディングを使用します。
  • ブラウザーのクライアントにはアクセストークンを使用し、API キーは決して公開しないでください。
例：ブランドボイスを保ったローカライズ

制作上の目的：承認済みの同一の話者アイデンティティを使い、英語の製品広告をスペイン語と日本語にローカライズします。

ワークフロー：

  1. タレント契約で、スペイン語と日本語での音声のクローン作成・ローカライズ、広告媒体、有効地域、キャンペーン期間が対象となっていることを確認します。
  2. 各対象言語の音声をローカライズするか、選定します。英語の音声が各言語でもネイティブだと決めつけないでください。
  3. 各市場向けに台本を翻訳・調整し、編集に合わせてタイミングを調整します。
  4. 製品名や地域固有の単語の発音エントリーを作成します。
  5. 字幕のタイミングが必要な場合は、POST /tts/bytes または SSE を使い、language: "es" と language: "ja" でテイクを生成します。
  6. ネイティブのレビュアーが発音、アクセント、感情的な適合性、コンプライアンスを評価します。

期待される結果：ブランドアイデンティティを保ちながら、ネイティブのリスナーに自然に聞こえる、言語別のファイルが作成されます。

失敗パターン：

  • 直訳すると、所定の時間内に収まりません。単に速度を上げるのではなく、コピーを書き直してください。
  • 製品名の発音が市場によって異なります。ロケールごとに別の発音辞書を使用してください。
  • 同意が英語のみを対象としています。音声のローカライズやクローン作成に進む前に中止してください。

バリエーション：

  • 正確な台本の制御よりもイントネーションやタイミングの維持が重要な場合は、人間のガイドパフォーマンスからボイスチェンジャーを使用します。
  • ブランドアイデンティティよりもネイティブらしい自然さが重要な場合は、ロケールごとに別のストック音声を使用します。
例：演技されたセリフへのボイスチェンジャーの使用

制作上の目的：俳優のコミカルなタイミングを保ちながら、承認済みのキャラクターボイスに変換します。

ワークフロー：

  1. 元の演技と変換先の音声の権利を確認します。
  2. 元のクリップを整えます。話者は1人とし、BGM、重なった発話、クリッピングがない状態にします。
  3. 変換先の voice[id] と本番用の出力形式を指定して、POST /voice-changer/bytes を使用します。
  4. 出力と元のクリップを比較し、タイミングとイントネーションが維持されているか確認します。
  5. 後処理でミックスします。音量コントロールを最終的なラウドネス調整に使わないでください。

期待される結果：変換先の音声で、セリフのタイミングとイントネーションが維持されます。

失敗パターン：

  • BGMやノイズが変換後の音声に残ったり、変換を妨げたりします。
  • 複数の話者によって変換が混乱します。
  • 法務レビューで変換先の音声の権利が認められません。

バリエーション：

  • ストリーミングイベント形式が便利な場合は、voice-changer/sse を使用します。
  • 元の演技の維持よりも、正確な文言、発音辞書、またはきれいな差し替え録音が重要な場合は、文字起こしから TTS を使用します。

ソースアンカーの確認日：2026-07-10

コメント

Markdown 対応