このトピックでは、音声合成のための CosyVoice Python SDK のパラメーターとインターフェイスの詳細について説明します。
中国 (北京) リージョンのモデルを使用するには、中国 (北京) リージョンの API キーページに移動してください。
ユーザーガイド:モデルの詳細とモデル選択のガイダンスについては、「リアルタイム音声合成 - CosyVoice」をご参照ください。
前提条件
Model Studio を有効化し、API キーを作成済みであること。セキュリティリスクを防ぐため、API キーをコードにハードコーディングするのではなく、API キーを環境変数としてエクスポートしてください。
説明サードパーティのアプリケーションやユーザーに一時的なアクセス権限を付与する場合、または機密データへのアクセスや削除などのリスクの高い操作を厳密に制御したい場合は、一時的な認証トークンの使用を推奨します。
長期的な API キーと比較して、一時的な認証トークンは有効期間が短い (60 秒) ため、より安全です。これらは一時的な呼び出しシナリオに適しており、API キー漏洩のリスクを効果的に低減できます。
一時的なトークンを使用するには、コード内の認証に使用する API キーを一時的な認証トークンに置き換えてください。
モデルと料金
モデル | 料金 | 無料クォータ (注) |
cosyvoice-v3-plus | 0.286706 ドル/10,000 文字 | 無料クォータなし |
cosyvoice-v3-flash | 0.14335 ドル/10,000 文字 | |
cosyvoice-v2 | 0.286706 ドル/10,000 文字 |
テキストとフォーマットの制限
テキスト長の制限
非ストリーミング呼び出しまたは単方向ストリーミング呼び出しの場合、1 回のリクエストのテキストは 20,000 文字を超えることはできません。
双方向ストリーミング呼び出しの場合、1 回のリクエストのテキストは 20,000 文字を超えることはできません。送信されるすべてのテキストの累積長は 200,000 文字を超えることはできません。
文字数カウントルール
簡体字または繁体字中国語、日本の漢字、韓国の漢字を含む中国語の文字は、2 文字としてカウントされます。句読点、アルファベット、数字、日本語のかな、韓国のハングルなど、その他のすべての文字は 1 文字としてカウントされます。
SSML タグはテキスト長の計算に含まれません。
例:
"你好"→ 2(你) + 2(好) = 4 文字"中A文123"→ 2(中) + 1(A) + 2(文) + 1(1) + 1(2) + 1(3) = 8 文字"中文。"→ 2(中) + 2(文) + 1(。) = 5 文字"中 文。"→ 2(中) + 1(スペース) + 2(文) + 1(。) = 6 文字"<speak>你好</speak>"→ 2(你) + 2(好) = 4 文字
エンコーディング形式
UTF-8 エンコーディングを使用してください。
数式のサポート
数式解析機能は、現在 cosyvoice-v2、cosyvoice-v3-flash、および cosyvoice-v3-plus モデルでのみ利用可能です。この機能は、基本的な算術、代数、幾何学など、小中学校で一般的に使用される数式をサポートします。
「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 メソッドを呼び出してテキストを合成し、バイナリ音声データを取得できます。
送信するテキストは 2,000 文字を超えることはできません。詳細については、SpeechSynthesizer クラスの call メソッドをご参照ください。
call メソッドを呼び出すたびに、新しい SpeechSynthesizer インスタンスを作成する必要があります。
単方向ストリーミング呼び出し
このメソッドは、単一の音声合成タスクを送信します。中間結果はコールバックを介してストリーミングされ、最終的な合成結果は ResultCallback コールバック関数を介してストリーミングされます。
SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターとResultCallback インターフェイスをアタッチし、call メソッドを呼び出して合成を実行します。その後、ResultCallback インターフェイスの on_data メソッドを介してリアルタイムの合成結果を取得できます。
送信するテキストの長さは 2,000 文字を超えることはできません。詳細については、SpeechSynthesizer クラスの call メソッドをご参照ください。
call メソッドを呼び出すたびに、新しい SpeechSynthesizer インスタンスを作成する必要があります。
双方向ストリーミング呼び出し
このメソッドでは、1 回の音声合成タスク内でテキストを複数回に分けて送信し、コールバックを介して合成結果をリアルタイムで受信できます。
入力をストリーミングするには、
streaming_callメソッドを複数回呼び出して、テキストの断片を順番に送信します。サーバーはテキストの断片を受信すると、自動的に文に分割します:完全な文はすぐに合成されます。
不完全な文はバッファリングされ、完全になってから合成されます。
streaming_completeメソッドを呼び出すと、サーバーは受信したが未処理のすべてのテキスト断片 (不完全な文を含む) を合成します。テキスト断片を送信する間隔は 23 秒を超えることはできません。超えた場合、「request timeout after 23 seconds」例外が発生します。
送信するテキストがこれ以上ない場合は、
streaming_completeメソッドを呼び出してタスクを終了する必要があります。サーバーは 23 秒のタイムアウトを強制します。クライアントはこの構成を変更できません。
SpeechSynthesizer クラスをインスタンス化できます。
SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターとResultCallback コールバックインターフェイスをアタッチします。
ストリーミングデータ
SpeechSynthesizer クラスの
streaming_callメソッドを複数回呼び出してデータをストリーミングします。これにより、合成するテキストがセグメント単位でサーバー側に送信されます。テキストを送信している間、サーバーはResultCallback インターフェイスの
on_dataメソッドを使用して、合成された結果をリアルタイムでクライアントに返します。streaming_callメソッドの各呼び出しで送信されるテキストセグメント (textパラメーター) の長さは 2,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 および cosyvoice-v3-plus モデルのクローン音声、および音声リストでサポートされているとマークされたシステム音声でのみ利用可能です。 デフォルト値はありません。このパラメーターが設定されていない場合、効果はありません。 音声合成には以下の効果があります:
|
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 モデルでのみサポートされています。 説明
|
callback | ResultCallback | いいえ |
主要なインターフェイス
SpeechSynthesizer クラス
SpeechSynthesizer クラスは、音声合成のメインインターフェイスです。このクラスは from dashscope.audio.tts_v2 import * を使用してインポートできます。
メソッド | パラメーター | 戻り値 | 説明 |
|
|
| テキストのセグメント全体を音声に変換します。テキストはプレーンテキストまたは SSML を含むことができます。
重要
|
|
| None | 合成するテキストをストリーミングします。SSML を含むテキストはサポートされていません。 このインターフェイスを複数回呼び出して、合成するテキストをセグメント単位でサーバーに送信できます。合成結果は、ResultCallback インターフェイスの 詳細については、「双方向ストリーミング呼び出し」をご参照ください。 |
|
| None | ストリーミング音声合成を終了します。 このメソッドは、タスクが完了するまで、 デフォルトでは、待機時間が 10 分を超えると待機を停止します。 詳細については、「双方向ストリーミング呼び出し」をご参照ください。 重要 双方向ストリーミング呼び出しを行う際は、このメソッドを呼び出してください。そうしないと、合成された音声が不完全になる可能性があります。 |
| None | 最後のタスクのリクエスト ID。 | 最後のタスクのリクエスト ID を取得します。 |
| None | 初回パケット遅延 | 初回パケット遅延を取得します。遅延は通常約 500 ms です。 初回パケット遅延は、テキストを送信してから最初の音声パケットを受信するまでの時間 (ミリ秒) です。タスクが完了した後に遅延を確認してください。 初めてテキストを送信する際には、WebSocket 接続を確立する必要があります。そのため、初回パケット遅延には接続確立にかかる時間が含まれます。 |
| None | 最後のメッセージ | 最後のメッセージを JSON 形式で取得します。これを使用して、タスク失敗のエラーを取得できます。 |
コールバックインターフェイス (ResultCallback)
単方向ストリーミング呼び出しまたは双方向ストリーミング呼び出しの場合、サーバーは主要なプロセス情報とデータをコールバックを介してクライアントに返します。返された情報とデータを処理するために、コールバックメソッドを実装する必要があります。
from dashscope.audio.tts_v2 import * を使用してインポートできます。
メソッド | パラメーター | 戻り値 | 説明 |
| None | None | サーバーとの接続が確立された直後に呼び出されます。 |
|
| None | サービスが応答を送信したときに呼び出されます。 |
| None | None | すべての合成データが返され、音声合成が完了した後に呼び出されます。 |
|
| None | 例外が発生したときに呼び出されます。 |
|
| None | サーバーが合成された音声を返したときに呼び出されます。 バイナリ音声データを結合して完全な音声ファイルを作成して再生するか、ストリーミング再生をサポートするプレーヤーでリアルタイムに再生します。 重要
|
| None | None | サービスが接続を閉じた後に呼び出されます。 |
応答
サーバーはバイナリ音声データを返します:
非ストリーミング呼び出し:SpeechSynthesizer クラスの
callメソッドから返されたバイナリ音声データを処理できます。単方向ストリーミング呼び出しまたは双方向ストリーミング呼び出しの場合、ResultCallback コールバックインターフェイスの
on_dataメソッドのパラメーター (バイトデータ) を処理できます。
エラーコード
トラブルシューティング情報については、「エラーメッセージ」をご参照ください。
その他の例
その他の例については、GitHub をご参照ください。
よくある質問
機能、課金、レート制限
Q:不正確な発音を修正するにはどうすればよいですか?
SSML を使用して、音声合成の出力をカスタマイズできます。
Q:音声合成はテキストの文字数に基づいて課金されます。各合成のテキスト長を確認または取得するにはどうすればよいですか?
これはロギングが有効になっているかどうかによります:
ロギングは無効になっています。
非ストリーミング呼び出しの場合、文字数カウントルールに従って文字数を計算できます。
または、ResultCallback コールバックインターフェイスの
on_eventメソッドのmessageパラメーターから情報を取得できます。messageは JSON 文字列であり、これを解析して現在のリクエストの課金対象文字数をcharactersパラメーターから取得します。受信した最後の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 を取得するにはどうすればよいですか?
以下の 2 つの方法のいずれかで取得できます:
ResultCallback コールバックインターフェイスの
on_eventメソッドでmessageJSON 文字列を解析します。SpeechSynthesizer の
get_last_request_idメソッドを呼び出します。
Q:SSML 機能が失敗するのはなぜですか?
以下を確認してください:
範囲が正しいことを確認してください。
最新バージョンの DashScope SDK をインストールしていることを確認してください。
正しいインターフェイスを使用していることを確認してください。SSML は SpeechSynthesizer クラスの
callメソッドでのみサポートされています。合成するテキストがプレーンテキストであり、必要なフォーマットを満たしていることを確認してください。詳細については、「SSML の概要」をご参照ください。
Q:音声が再生できないのはなぜですか?
以下のシナリオに基づいてこの問題をトラブルシューティングしてください:
音声は、.mp3 ファイルなどの完全なファイルとして保存されます。
音声フォーマットの一貫性:リクエストパラメーターで指定された音声フォーマットがファイル拡張子と一致していることを確認してください。例えば、リクエストパラメーターで音声フォーマットが WAV に設定されているのに、ファイル拡張子が .mp3 の場合、再生が失敗する可能性があります。
プレーヤーの互換性:ご使用のプレーヤーが音声ファイルのフォーマットとサンプルレートをサポートしていることを確認してください。例えば、一部のプレーヤーは高いサンプルレートや特定の音声エンコーディングをサポートしていない場合があります。
音声がストリーミングモードで再生される場合
音声ストリームを完全なファイルとして保存し、再生を試みてください。ファイルの再生に失敗した場合は、最初のシナリオのトラブルシューティング手順をご参照ください。
ファイルが正しく再生される場合、問題はストリーミング再生の実装にある可能性があります。ご使用のプレーヤーがストリーミング再生をサポートしていることを確認してください。
ストリーミング再生をサポートする一般的なツールとライブラリには、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.pemシンボリックリンクを作成して Python の 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 の Q&A をご参照ください。