DashScope Python SDK を使用して、非ストリーミング、一方向ストリーミング、または双方向ストリーミングモードで、CosyVoice のリアルタイム音声合成をアプリケーションに統合します。
サービスエンドポイント
SDK のインターフェースアドレスは、Client の構築パラメーター workspace/region で決まります(下記のアドレスに対応し、WorkspaceId を含みます)。他のリージョンに切り替えるには、Client の構築パラメーターを対応するリージョンの値に変更してください。
- Singapore
- China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference{WorkspaceId} を実際のワークスペース ID に置き換えます。コアリソース(client.audio.tts)
リソースパス:client.audio.tts
機能:WebSocket ベースの音声合成で、一次性合成(synthesize)、ストリーミング合成(stream)、双方向ストリーミングセッション(connect)の 3 つの呼び出し形態を提供します。
呼び出しエントリ
synthesize() - 非ストリーミング呼び出し
メソッドシグネチャ:
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
text | str | はい | 合成する全文テキスト。最大長: 20,000 文字。 |
bytes。
説明: 非ストリーミング呼び出しで、ブロックして待機し、完全な音声データを一度に返します。短いテキストで、リアルタイム性の要件が厳しくないシナリオに適しています。synthesize と stream は呼び出しごとにセッションを自前で構築するため、インスタンスを再利用する必要はありません。
stream() - ストリーミング呼び出し
メソッドシグネチャ:
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
text | str | はい | 合成する全文テキスト。最大長: 20,000 文字。 |
Iterator[bytes]、チャンクごとに産出される音声データ。
説明: ストリーミング合成で、完全なテキストを一度に送信し、音声をチャンクごとに産出します(Iterator[bytes])。リアルタイム性の要件が高い短いテキストの音声合成シナリオに適しています。テキストを分割して送信する必要がある場合は、双方向ストリーミングセッション(connect)を使用してください。
send_text() - ストリーミング入力(セッションメソッド)
双方向ストリーミングセッション(client.audio.tts.connect(...))でテキストを分割して送信します。
メソッドシグネチャ:
text は現在合成対象のテキストセグメントです。send_text は複数回呼び出してテキストを追加できます。1 回の呼び出しあたりの最大長は 20,000 文字、累計の最大長は 200,000 文字です。テキストの送信と音声の受信は並行して行う必要があります(audio_chunks()/events() および stop と組み合わせて使用します)。
stop() - ストリーミング入力の終了(セッションメソッド)
メソッドシグネチャ:
audio_chunks()/events() を消費し続ける必要があります。このメソッドを呼び出さないと、末尾のテキストが音声に変換されない場合があります。
cancel() - ストリーミング合成のキャンセル(セッションメソッド)
メソッドシグネチャ:
会話指標と応答(セッション属性)
first_package_delay:float。テキストを送信してから最初の音声データチャンクを受信するまでのレイテンシー(ミリ秒)。合成完了後に読み取る必要があります。usage:dict。直近の合成タスクの使用量情報。last_response:dict。直近の合成タスクの応答メッセージ(header/payloadキーを含む)。直近のリクエストの request_id はsession.last_responseのheaderから取得でき、問題の切り分けやログとの関連付けに使用できます。
リクエストパラメーター
以下のパラメーターは client.audio.tts の synthesize/stream/connect メソッドで設定し、合成音声のモデル、音色、フォーマット、および音声特性を制御します(model、voice、format、sample_rate、volume、rate、pitch、language_hints、enable_ssml は具名パラメーターで、その他のパラメーターは parameters ディクショナリで渡します)。
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
model | str | はい | モデル名。 |
voice | str | はい | 音声合成に使用する音声。
|
format | str | いいえ | 音声のエンコーディング形式。デフォルト値: mp3。mp3、wav、pcm などの形式をサポートします。サンプリングレートは sample_rate パラメーターで設定し、デフォルトは 22050 です。 |
volume | int | いいえ | 音量レベル。デフォルト値: 50。有効な値: [0, 100]。 |
rate | float | いいえ | 話速。デフォルト値: 1.0。有効な値: [0.5, 2.0]。 |
pitch | float | いいえ | ピッチ。デフォルト値: 1.0。有効な値: [0.5, 2.0]。 |
bit_rate | int | いいえ | kbps 単位のオーディオビットレート。オーディオ形式が mp3 または opus の場合は、bit_rate を使用してビットレートを調整します。デフォルト値: 32。有効な値: [6, 510]。bit_rate は parameters ディクショナリで設定します: |
word_timestamp_enabled | bool | いいえ | 単語レベルのタイムスタンプを有効にするかどうかを指定します。デフォルト値: false。ストリーミング出力モードでのみ使用可能です。サポートされている音声は、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 のクローン音声、およびCosyVoice 音声リストでサポート対象として記載されているシステム音声です。他のモデルのクローン音声はこの機能をサポートしていません。word_timestamp_enabled は parameters ディクショナリで設定します: |
seed | int | いいえ | 合成出力のバリエーションを制御するためのランダムシード。モデルのバージョン、テキスト、音声、およびその他のパラメーターが変更されない場合、同じシードを使用すると同一の結果が生成されます。デフォルト値: 0。有効な値: [0, 65535]。 |
language_hints | list[str] | いいえ | 出力品質を向上させるために、音声合成のターゲット言語を指定します。数字の発音、略語の展開、記号の読み上げ、または少数言語の合成が期待どおりでない場合に、このパラメーターを使用します。例:
有効な値
|
instruction | str | いいえ | 方言、感情、話し方などの合成特性を制御します。使用方法の詳細については、「Instruction control」をご参照ください。 |
enable_aigc_tag | bool | いいえ | 生成された音声に AIGC ウォーターマークを埋め込むかどうかを指定します。true に設定すると、サポートされている形式 (wav/mp3/opus) の音声ファイルにウォーターマークが埋め込まれます。デフォルト値: false。cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 のみがこの機能をサポートしています。 enable_aigc_tag、aigc_propagator、および aigc_propagate_id は、parameters ディクショナリで設定します: |
aigc_propagator | str | いいえ | AIGC 透かしの ContentPropagator フィールドを設定してコンテンツプロパゲーターを識別するもので、enable_aigc_tag が true の場合にのみ有効になります。デフォルト値: Alibaba Cloud UID。cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 のみがこの機能をサポートしています。 parameters ディクショナリで設定します。enable_aigc_tag の例をご参照ください。 |
aigc_propagate_id | str | いいえ | AIGC ウォーターマークの PropagateID フィールドを設定して、特定の伝播アクションを一意に識別します。enable_aigc_tag が true の場合にのみ有効になります。デフォルト値: 現在の音声合成リクエストのリクエスト ID。cosyvoice-v3-flash、cosyvoice-v3-plus、cosyvoice-v2 のみがこの機能をサポートしています。 parameters ディクショナリで設定します。enable_aigc_tag の例を参照してください。 |
hot_fix | dict | いいえ | 合成前に適用される発音補正とテキスト置換を設定します。 この機能は cosyvoice-v2 ではサポートされていません。
|
enable_markdown_filter | bool | いいえ | cosyvoice-v3-flash のクローン音声のみがこの機能をサポートしています。
enable_markdown_filter は parameters ディクショナリで設定します: |
会話とイベント反復
ストリーミング合成ではコールバックインターフェイスを使用しなくなりました:音声とサーバーイベントはセッションの反復メソッドで受信します。stream()/synthesize() ではセッション管理は不要です。双方向ストリーミングセッション(client.audio.tts.connect(...))のライフサイクルは:with コンテキストに入ると自動的に接続を確立 → 複数回 send_text() → stop() → すべての結果を読み取る → コンテキストから抜けると自動的に閉じる、です。
audio_chunks() - 音声データの反復
メソッドシグネチャ:
Iterator[bytes]。チャンクごとに産出される音声のバイナリデータフラグメントで、フォーマットは format パラメーターで指定されます。
説明:受信スレッドで反復処理し、音声データをチャンク単位で受信します。合成中は複数のチャンクが産出されます。データをファイルに書き込んだり、再生デバイスに送ったりできます。同一セッションで許可される events() または audio_chunks() の読み取り者は 1 つだけです。
events() - サーバーイベントの反復
メソッドシグネチャ:
dict、header(リクエスト情報)と payload(出力情報)を含む)と音声 bytes を同時に産出します。payload.output にはイベントタイプ、元テキストなどの情報が含まれます。詳細はevents() イベントの output フィールドをご参照ください。
説明:受信スレッドでサーバーからの返信を反復処理します。合成イベントの出力情報(イベントタイプ、元テキスト、文情報など)を含み、payload.output に直接アクセスして詳細を取得できます。
エラー処理
合成中にエラーが発生すると、ws 層は DashScopeError 例外としてスローされ、例外がトリガーされると接続は自動的に閉じられます。送信/受信処理で try/except で捕捉し、問題の切り分けに役立てるためエラーログを記録できます:
セッションのライフサイクル
withコンテキストに入ると自動的に接続を確立します(この前に音声出力ストリームの初期化やファイルのオープンなどのリソースを準備できます)。- すべてのテキストの合成が完了し、すべての音声データが産出された後、
events()/audio_chunks()の反復処理が終了します。その後first_package_delayなどのパフォーマンス指標を読み取れます。 withコンテキストから抜けると自動的に接続を閉じます(この後に音声再生デバイスなどのリソースを解放できます)。
events() イベントの output フィールド
セッションの events() が産出するイベント dict の payload.output には、合成イベントの出力情報が含まれており、合成の進捗の追跡や文ごとの詳細の取得に使用できます。output フィールドの構造は次のとおりです。
| フィールド | 型 | 説明 |
|---|---|---|
type | str | イベントタイプ。値は、 sentence-begin (文の合成開始)、 sentence-synthesis (文の合成進行中)、または sentence-end (文の合成完了) のいずれかです。 |
original_text | str | 現在の文の元のテキスト。 sentence-begin および sentence-end イベントで返されます。 |
sentence | dict | 文情報。 index (文のシーケンス番号) と words (単語リスト。 word_timestamp_enabled が有効な場合にタイムスタンプ情報を含む) が含まれます。 |
コード例
SDK は、次の合成モードをサポートしています:
- ノンストリーミング呼び出し:ブロッキング型で、完全なテキストを一度に送信し、完全な音声を直接返します。短いテキストの音声合成シナリオに適しています。
- 単方向ストリーミング呼び出し:ノンブロッキング型で、完全なテキストを一度に送信し、
streamが返す音声チャンクを反復処理してデータを受信します。リアルタイム性の要件が高い短いテキストの音声合成シナリオに適しています。 - 双方向ストリーミング呼び出し:ノンブロッキング型で、テキストセグメントを複数回に分けて送信し、セッションの
audio_chunks()/events()の反復処理で増分合成された音声ストリームをリアルタイムに受信します。リアルタイム性の要件が高い長いテキストの音声合成シナリオに適しています。
- ノンストリーミング
- 単方向ストリーミング
- 双方向ストリーミング
DashScopeError 例外がトリガーされます。