本トピックでは、CosyVoice 音声合成 Python SDK のパラメーターおよびメソッドについて説明します。
ユーザーガイド: モデルの概要および選択推奨事項については、「リアルタイム音声合成 – CosyVoice/Sambert」をご参照ください。
前提条件
-
Model Studio を有効化し、API キーを作成済みである必要があります。セキュリティリスクを防止するため、API キーをコード内にハードコーディングせず、環境変数としてエクスポートしてください。
説明サードパーティアプリケーションまたはユーザーに一時的なアクセス権限を付与する場合、または機密データへのアクセスや削除といった高リスク操作を厳密に制御したい場合は、一時認証トークンの使用を推奨します。
長期的な API キーと比較して、一時認証トークンは有効期限が短い(60 秒)ため、より安全です。一時的な呼び出しシナリオに適しており、API キーの漏洩リスクを効果的に低減できます。
一時トークンを使用するには、コード内の認証用 API キーを一時認証トークンに置き換えてください。
モデルおよび料金
詳細については、「リアルタイム音声合成 – CosyVoice/Sambert」をご参照ください。
音声合成におけるテキストの制限およびフォーマット要件
テキスト長の制限
非ストリーミング呼び出しまたは片方向ストリーミング呼び出しの場合、各テキスト送信は 20,000 文字を超えてはなりません。
双方向ストリーミング呼び出しの場合、各テキスト送信は 20,000 文字を超えてはならず、すべての送信の合計文字数は 200,000 文字を超えてはなりません。
文字数計算ルール
漢字(簡体字、繁体字、日本語の漢字、韓国の漢字を含む)は 2 文字としてカウントされます。その他のすべての文字(句読点、アルファベット文字、数字、日本語/韓国の仮名/ハングルを含む)は 1 文字としてカウントされます。
SSML タグの内容はテキスト長の計算対象外です。
例:
"你好"→ 2(你)+2(好)=4 文字"中A文123"→ 2(各中国語文字)+1('A')+2(各中国語文字)+1('1')+1('2')+1('3')=8 文字"Chinese."→ 2(zhong)+2(wen)+1(句点)=5 文字"中 文。"→ 2(中)+1(半角スペース)+2(文)+1(句点)=6 文字"<speak>Hello</speak>"→ 2(ni)+2(hao)=4 文字
エンコード形式
UTF-8 エンコードを使用します。
数式のサポート
数式のパースは、cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 モデルのみでサポートされています。小学校および中学校で一般的に使用される数式(基本演算、代数、幾何学など)をサポートします。
詳細については、「LaTeX 数式から音声へ」をご参照ください。
音声合成マークアップ言語 (SSML) のサポート
音声合成マークアップ言語 (SSML) 機能は、cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 モデルのクローン音声、および音声一覧で「対応」と明記されたシステム音声でのみ利用可能です。この機能を利用するには、以下の条件を満たす必要があります:
DashScope SDK バージョン 1.23.4 以降を使用する必要があります。
非ストリーミング呼び出しおよび片方向ストリーミング呼び出し(つまり、SpeechSynthesizer クラスの
callメソッド)のみがサポートされます。双方向ストリーミング呼び出し(つまり、SpeechSynthesizer クラスのstreaming_callメソッド)はサポートされません。使用方法は標準音声合成と同一です。SSML 形式のテキストを、SpeechSynthesizer クラスの
callメソッドに渡すことができます。
クイックスタート
SpeechSynthesizer クラスは、コアとなる音声合成メソッドを提供し、以下の呼び出しタイプをサポートします:
非ストリーミング呼び出し:ブロッキング方式。テキスト全体を一度に送信し、完全な音声応答を即座に受信します。短文の音声合成に適しています。
片方向ストリーミング呼び出し:ノンブロッキング方式。テキスト全体を一度に送信し、コールバック関数経由で音声データ(分割されている可能性あり)を受信します。リアルタイム性が高く、短文の音声合成に適しています。
双方向ストリーミング呼び出し:ノンブロッキング方式。テキストを複数のセグメントに分割して送信し、コールバック関数経由でリアルタイムに合成された音声ストリームを段階的に受信します。リアルタイム性が高く、長文の音声合成に適しています。
非ストリーミング呼び出し
コールバック関数を指定せずに単一の音声合成タスクを送信できます。結果は中間ストリーミング出力なしで一度に返されます。
SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターをバインドした後、call メソッドを呼び出して音声合成を行い、バイナリ音声データを取得します。
テキストは 20,000 文字を超えてはなりません。詳細については、SpeechSynthesizer クラスの call メソッドをご参照ください。
call メソッドを呼び出す前に、SpeechSynthesizer インスタンスを再初期化してください。
片方向ストリーミング呼び出し
単一の音声合成タスクを送信し、コールバック経由で中間結果を受信できます。合成結果は ResultCallback コールバック関数を通じて返されます。
SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターおよびコールバックインターフェイス (ResultCallback)をバインドした後、call メソッドを呼び出して、コールバックインターフェイス (ResultCallback) の on_data メソッド経由でリアルタイムに合成結果を受信します。
テキストは 20,000 文字を超えてはなりません。詳細については、SpeechSynthesizer クラスの call メソッドをご参照ください。
call メソッドを呼び出す前に、SpeechSynthesizer インスタンスを再初期化してください。
双方向ストリーミング呼び出し
単一の音声合成タスク内でテキストを断片的に送信し、コールバック経由でリアルタイムに結果を受信できます。
ストリーミング入力中に、
streaming_callを複数回呼び出して、順番にテキスト断片を送信できます。サーバーが自動的にこれらを文に分割します。完全な文は即座に合成されます。
不完全な文は、完全になるまでバッファーに保持され、その後合成されます。
streaming_completeを呼び出すと、サーバーは受信済みだが未処理のすべての断片(不完全な文を含む)を強制的に合成します。テキスト断片の送信間隔は 23 秒を超えてはなりません。超えると「23 秒経過後のリクエストタイムアウト」エラーが返されます。
これ以上送信するテキストがない場合は、タスクを終了するために速やかに
streaming_completeメソッドを呼び出してください。サーバーは固定の 23 秒タイムアウトを適用します。クライアント側でこの設定を変更することはできません。
SpeechSynthesizer クラスのインスタンス化
SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターおよびコールバックインターフェイス (ResultCallback)をバインドします。
ストリーミング
SpeechSynthesizer クラスの
streaming_callメソッドを複数回呼び出して、合成用のテキスト断片を送信します。テキストを送信すると、サーバーはコールバックインターフェイス (ResultCallback) の
on_dataメソッドを用いて、クライアントにリアルタイムで合成結果を返信します。streaming_callメソッド(textパラメーター)への各送信は 20,000 文字を超えてはならず、すべての送信の合計は 200,000 文字を超えてはなりません。処理の終了
SpeechSynthesizer クラスの
streaming_completeメソッドを呼び出して音声合成を終了します。このメソッドは、コールバックインターフェイス (ResultCallback) の
on_completeまたはon_errorコールバックがトリガーされるまで、現在のスレッドをブロックします。必ずこのメソッドを呼び出してください。呼び出さないと、末尾のテキストが音声に変換されない可能性があります。
リクエストパラメーター
SpeechSynthesizer クラス のコンストラクターでリクエストパラメーターを設定できます。
パラメーター | 型 | 必須 | 説明 |
model | str | はい | 音声合成 モデル。 異なるモデルバージョンでは、対応する音声バージョンが必要です:
|
voice | str | はい | 音声合成に使用する音声。 システム音声およびクローン音声をサポート:
|
format | enum | いいえ | 音声エンコーディング形式およびサンプルレートを指定します。
説明 デフォルトのサンプルレートは、選択した音声に最適なレートです。出力はデフォルトでこのレートを使用しますが、ダウンサンプリングまたはアップサンプリングもサポートされます。 サポートされるフォーマットおよびサンプルレートは以下のとおりです:
|
volume | int | いいえ | ボリューム。 デフォルト値:50。 範囲:[0, 100]。50 は標準ボリュームを表します。ボリュームはこの値に対して線形関係にあります。0 はミュート、100 は最大ボリュームです。 重要 このフィールドは DashScope SDK のバージョンによって異なります:
|
speech_rate | float | いいえ | 話速。 デフォルト値:1.0。 範囲:[0.5, 2.0]。1.0 は標準の話速です。1.0 より小さい値は話速を遅くし、1.0 より大きい値は話速を速くします。 |
pitch_rate | float | いいえ | ピッチ。この値はピッチ調整の乗数として機能しますが、知覚されるピッチ変化との関係は厳密には線形でも対数的でもありません。適切な値はテストにより選択してください。 デフォルト値:1.0。 範囲:[0.5, 2.0]。1.0 は音声の自然なピッチです。1.0 より大きい値はピッチを上げ、1.0 より小さい値はピッチを下げます。 |
bit_rate | int | いいえ | 音声ビットレート(kbps)。音声フォーマットが Opus の場合、 デフォルト値:32。 範囲:[6, 510]。 説明
|
word_timestamp_enabled | bool | いいえ | 単語レベルのタイムスタンプを有効化します。 デフォルト:False。
この機能は、cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 のクローン音声、および音声一覧でタイムスタンプ対応と明記されたシステム音声でのみ動作します。 タイムスタンプはコールバックインターフェイスでのみ利用可能です。 説明
|
seed | int | いいえ | 合成効果を変化させるために生成時に使用される乱数シード。同じモデルバージョン、テキスト、音声、およびその他のパラメーターで、同じシードを使用すると、同一の合成結果が再現されます。 デフォルト値:0。 範囲:[0, 65535]。 |
language_hints | list[str] | いいえ | 音声合成の対象言語を指定し、合成品質を向上させます。 数字、略語、記号の発音や少数言語の合成効果が期待通りでない場合に使用します。例:
範囲:
注記:このパラメーターは配列ですが、現在のバージョンでは先頭の要素のみが処理されます。そのため、1 つの値のみを渡してください。 重要 このパラメーターは音声合成の対象言語を指定します。これは音声クローン作成時のサンプル音声の言語とは無関係です。クローン作成タスクのソース言語を設定するには、「CosyVoice 音声クローン API」をご参照ください。 |
instruction | str | いいえ | 方言、感情、役割などの合成効果を制御する命令を設定します。この機能は、cosyvoice-v3-flash モデルのクローン音声、および音声一覧で「Instruct 対応」と明記されたシステム音声でのみ適用されます。 長さ制限:100 文字。 漢字(簡体字/繁体字、日本語の漢字、韓国の漢字を含む)は 2 文字としてカウントされます。その他のすべての文字(句読点、アルファベット、数字、日本語/韓国語の仮名/ハングルなど)は 1 文字としてカウントされます。 使用要件(モデルごとに異なります):
|
enable_aigc_tag | bool | いいえ | 生成された音声に目に見えない AIGC 識別子を追加します。True に設定すると、識別子が対応するフォーマット(WAV、MP3、OPUS)に埋め込まれます。 デフォルト:False。 この機能は cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 のみでサポートされます。 説明
|
aigc_propagator | str | いいえ | AIGC 識別子の デフォルト:Alibaba Cloud UID。 この機能は cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 のみでサポートされます。 説明
|
aigc_propagate_id | str | いいえ | AIGC 識別子の デフォルト:この音声合成リクエストのリクエスト ID。 この機能は cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 のみでサポートされます。 説明
|
hot_fix | dict | いいえ | 特定の単語の発音をカスタマイズしたり、合成対象のテキストを置き換えたりするためのテキストホットフィックス構成です。この機能は、cosyvoice-v3-flash のクローン音声でのみサポートされます。 パラメーター:
例: |
enable_markdown_filter | bool | いいえ | Markdown フィルターを有効化します。有効化すると、システムが合成前に入力テキストから Markdown 記号を自動的にフィルターし、それらがテキスト内容として読み上げられるのを防ぎます。この機能は、cosyvoice-v3-flash のクローン音声でのみサポートされます。 デフォルト:False。 値:
説明
|
callback | ResultCallback | いいえ |
主要インターフェイス
SpeechSynthesizer クラス
SpeechSynthesizer クラスは、from dashscope.audio.tts_v2 import * を使用してインポートします。このクラスは、コアとなる音声合成メソッドを提供します。
メソッド | パラメーター | 戻り値 | 説明 |
|
|
| テキスト全体(プレーンテキストまたはSSML を含むテキスト)を音声に変換します。
重要
|
|
| None | テキストをストリーミングして合成します(SSML はサポートされません)。 このメソッドを複数回呼び出して、テキスト断片をサーバーに送信します。コールバックインターフェイス (ResultCallback) の 「双方向ストリーミング呼び出し」をご参照ください。 |
|
| None | ストリーミング音声合成を終了します。 このメソッドは N ミリ秒( デフォルトでは、10 分後に待機を停止します。 「双方向ストリーミング呼び出し」をご参照ください。 重要 双方向ストリーミング呼び出しでは、必ずこのメソッドを呼び出してください。呼び出さないと、合成された音声が欠落する可能性があります。 |
| なし | 最後のタスクのリクエスト ID | 最後のタスクのリクエスト ID を取得します。 |
| なし | 最初のパッケージ遅延 | タスク終了後に、現在のタスクの最初のパッケージ遅延を取得します。最初のパッケージ遅延は、テキスト送信から最初の音声パッケージ受信までの時間をミリ秒単位で表します。 最初のパッケージ遅延に影響を与える要因:
典型的な遅延範囲:
最初のパッケージ遅延が高すぎる場合(>2000 ms)、以下の対策を検討してください:
|
| なし | 最後のメッセージ | 最後のメッセージ(JSON 形式)を取得します。タスク失敗エラーの検出に役立ちます。 |
コールバックインターフェイス(ResultCallback)
片方向ストリーミング呼び出しまたは双方向ストリーミング呼び出しでは、サーバーがステータス情報およびデータをコールバック経由で返します。サーバーの応答を処理するために、コールバックメソッドを実装する必要があります。
このインターフェイスは、from dashscope.audio.tts_v2 import * を使用してインポートできます。
メソッド | パラメーター | 戻り値 | 説明 |
| なし | なし | サーバーへの接続直後に呼び出されます。 |
|
| なし | サーバーが応答したときに呼び出されます。 |
| なし | なし | すべての合成データが返された後(音声合成完了)に呼び出されます。 |
|
| なし | エラーが発生したときに呼び出されます。 |
|
| なし | サーバーが合成音声を返したときに呼び出されます。 バイナリ音声データを結合して完全な音声ファイルを作成し、プレーヤーで再生することも、ストリーミング再生に対応するプレーヤーでリアルタイム再生することもできます。 重要
|
| なし | なし | サーバーが接続を閉じた後に呼び出されます。 |
応答
サーバーはバイナリ音声データを返します。
非ストリーミング呼び出しでは、SpeechSynthesizer クラス の
callメソッドが返すバイナリ音声データを処理できます。片方向ストリーミング呼び出しまたは双方向ストリーミング呼び出しでは、コールバックインターフェイス (ResultCallback) の
on_dataメソッドのパラメーター(bytes)を処理できます。
エラーコード
エラーが発生した場合は、「エラーメッセージ」を参照してトラブルシューティングを行ってください。
その他のサンプル
その他のサンプルについては、「GitHub」をご参照ください。
よくある質問
機能、課金、およびレート制限
Q:発音が不正確な場合、どのような解決策を試せますか?
SSML を使用して音声合成効果をカスタマイズできます。
Q:各合成のテキスト長を確認または取得するにはどうすればよいですか?課金は文字数に基づきます。
取得方法はログの有効/無効に依存します:
ログが無効な場合
非ストリーミング呼び出しでは、文字数計算ルールに基づいて手動で長さを計算できます。
その他の呼び出しタイプでは、コールバックインターフェイス (ResultCallback) の
on_eventメソッドのmessageパラメーターから課金対象文字数(characters)を取得できます。messageは JSON 文字列です。最後に受信したmessageを使用してください。
ログが有効な場合
コンソールに課金対象文字数を含むログが出力されます。
charactersフィールドが課金対象文字数を示します。最後に出力されたログの値を使用してください。2025-08-27 11:02:09,429 - dashscope - speech_synthesizer.py - on_message - 454 - DEBUG - <<<recv {"header":{"task_id":"62ebb7d6cb0a4080868f0edb######","event":"result-generated","attributes":{}},"payload":{"output":{"sentence":{"words":[]}},"usage":{"characters":15}}}
トラブルシューティング
コードでエラーが発生した場合は、「エラーコード」の情報を使用してトラブルシューティングを行ってください。
Q:リクエスト ID を取得するにはどうすればよいですか?
以下のいずれかの方法で取得できます:
コールバックインターフェイス (ResultCallback) の
on_eventメソッドの JSON 文字列messageを解析します。SpeechSynthesizer の
get_last_request_idメソッドを呼び出します。
Q:なぜ SSML が失敗しますか?
以下の手順でトラブルシューティングを行ってください:
すべての制限および制約を満たしているか確認します。
正しいメソッドを使用しているか確認します。SpeechSynthesizer クラス の
callメソッドのみが SSML をサポートします。テキストがプレーンテキストであり、フォーマット要件を満たしているか確認します。詳細については、「SSML の概要」をご参照ください。
Q:なぜ音声を再生できないのですか?
各シナリオごとに以下のようにトラブルシューティングを行ってください:
シナリオ:完全なファイルとして保存された音声(例:xx.mp3)
音声フォーマットの一貫性:リクエストパラメーターで指定した音声フォーマットがファイル拡張子と一致しているか確認します。たとえば、リクエストで WAV フォーマットを指定しているのにファイル拡張子が MP3 の場合、再生が失敗する可能性があります。
プレーヤーの互換性:プレーヤーが音声ファイルのフォーマットおよびサンプルレートをサポートしているか確認します。一部のプレーヤーは高いサンプルレートまたは特定の音声エンコーディングをサポートしていない場合があります。
シナリオ:ストリーミング音声再生
音声ストリームを完全なファイルとして保存し、プレーヤーで再生を試みます。ファイルが再生できない場合は、シナリオ 1 のトラブルシューティング方法を参照してください。
ファイルが正しく再生される場合、問題はストリーミング再生の実装にある可能性があります。プレーヤーがストリーミング再生をサポートしているか確認します。
ストリーミング再生をサポートする一般的なツールおよびライブラリには、ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (JavaScript) などがあります。
Q:なぜ音声再生が途切れるのですか?
各シナリオごとに以下のようにトラブルシューティングを行ってください:
テキスト送信速度の確認:テキスト送信の間隔が適切であるか確認します。前の音声の再生が終了した後、次の文がすぐに送信されない状況を避けてください。
コールバック関数のパフォーマンスの確認:
コールバック関数に、ブロッキングを引き起こす過剰なビジネスロジックが含まれていないか確認します。
コールバック関数は WebSocket スレッドで実行されます。ブロックされると、WebSocket がネットワークパケットを受信する能力に影響を与え、音声受信の途切れにつながる可能性があります。
WebSocket スレッドのブロッキングを避けるため、音声データを別の音声バッファーに書き込み、別のスレッドで読み取りおよび処理を行ってください。
ネットワーク安定性の確認:ネットワークの変動による音声送信の中断や遅延を避けるため、安定したネットワーク接続を確保してください。
Q:なぜ音声合成が遅いのですか(合成時間が長い)?
以下のようにトラブルシューティングを行ってください:
入力間隔の確認
ストリーミング音声合成の場合、テキスト送信間隔が長すぎないか確認します。たとえば、前のセグメントが送信されてから次のセグメントが送信されるまでに数秒かかる場合などです。過剰な間隔は、合計合成時間を増加させます。
パフォーマンスメトリックの分析
最初のパッケージ遅延:通常約 500 ms。
RTF(RTF = 合計合成時間 / 音声持続時間):通常 1.0 未満。
Q:合成音声の発音の誤りを修正するにはどうすればよいですか?
SSML の <phoneme> タグを使用して、正しい発音を指定します。
Q:なぜ音声が返されないのですか?なぜ音声の一部が欠落しているのですか?(音声の欠落)
SpeechSynthesizer クラス の streaming_complete メソッドを呼び出したことを確認してください。サーバーは、合成を開始する前に十分なバッファーされたテキストを待機します。streaming_complete メソッドを呼び出さない場合、末尾のテキストが未処理のままになる可能性があります。
Q:SSL 証明書の検証失敗を修正するにはどうすればよいですか?
システムルート証明書をインストール
sudo yum install -y ca-certificates sudo update-ca-trust enableアプリケーションに以下のコードを追加
import os os.environ["SSL_CERT_FILE"] = "/etc/ssl/certs/ca-bundle.crt"
Q:macOS で「SSL: CERTIFICATE_VERIFY_FAILED」エラーが発生するのはなぜですか? (websocket closed due to [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000))
WebSocket に接続する際に OpenSSL 証明書の検証エラーが発生する場合があります。これは多くの場合、Python の証明書構成が正しくないことが原因です。この問題は手動で修正できます:
システム証明書をエクスポートし、環境変数を設定:以下のコマンドを実行して、すべての macOS 証明書をファイルにエクスポートし、Python および関連ライブラリのデフォルトパスとして設定します。
security find-certificate -a -p > ~/all_mac_certs.pem export SSL_CERT_FILE=~/all_mac_certs.pem export REQUESTS_CA_BUNDLE=~/all_mac_certs.pemPython OpenSSL 構成を修正するためのシンボリックリンクを作成:Python OpenSSL 構成に証明書が不足している場合、シンボリックリンクを作成できます。以下のコマンドのパスを、ご利用の Python インストールディレクトリに置き換えてください。
# 3.9 はバージョン例です。インストールされている Python のバージョンに合わせて調整してください。 ln -s /etc/ssl/* /Library/Frameworks/Python.framework/Versions/3.9/etc/opensslターミナルを再起動し、キャッシュをクリア:ターミナルを閉じて再度開き、環境変数を適用します。キャッシュをクリアし、WebSocket 接続を再試行してください。
これらの手順により、証明書の構成ミスによって引き起こされる接続の問題を解決できます。問題が解決しない場合は、サーバーの証明書構成を確認してください。
Q:なぜ「AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?」というエラーが発生するのですか?
このエラーは、websocket-client パッケージが不足しているか、バージョンが一致しない場合に発生します。これを解決するには、以下のコマンドを実行してください:
pip uninstall websocket-client
pip uninstall websocket
pip install websocket-client権限および認証
Q: API キーを CosyVoice 音声合成サービスのみに使用し、他の Model Studio モデルでは使用しないようにしたいです(権限の隔離)。どうすればよいですか?
新しいワークスペースを作成し、特定のモデルのみを権限付与することで、API キーの範囲を制限できます。詳細については、「ワークスペース管理」をご参照ください。
その他の質問
詳細については、GitHub の「QA」をご参照ください。