前提条件
Qwen-Audio-TTS
サービスエンドポイント
SDK のサービスエンドポイントは、Client の構築パラメーター workspace/region で決まります(下記のアドレスに対応し、WorkspaceId を含みます)。別のリージョンに切り替えるには、Client の構築パラメーターを対象リージョンの値に変更してください。
- Singapore
- China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference{WorkspaceId} を実際のワークスペース ID に置き換えます。CosyVoice
サービスエンドポイント
SDK のインターフェースアドレスは、Client の構築パラメーター workspace/region で決まります(下記のアドレスに対応し、WorkspaceId を含みます)。他のリージョンに切り替えるには、Client の構築パラメーターを対応するリージョンの値に変更してください。
- Singapore
- China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference{WorkspaceId} を実際のワークスペース ID に置き換えます。クイックスタート
Qwen-Audio-TTS
SDK は、次の合成モードをサポートしています:
- 非ストリーミング: 完全なテキストを一度に送信し、完全な音声を直接返すブロッキング呼び出しです。短いテキストの音声合成に最適です。
- 一方向ストリーミング: 完全なテキストを一度に送信し、
streamが返すオーディオチャンクを反復処理して音声データを受信するノンブロッキング呼び出しです。低レイテンシーが求められる短いテキストのシナリオに最適です。 - 双方向ストリーミング: テキストを複数のセグメントで送信し、セッションの
audio_chunks()/events()を反復処理して、リアルタイムで増分合成された音声ストリームを受信するノンブロッキング呼び出しです。低レイテンシーが求められる長いテキストのシナリオに最適です。
- 非ストリーミング
- 一方向ストリーミング
- 双方向ストリーミング
1 回の呼び出しで送信されるテキストは 20,000 文字を超えてはなりません。この制限を超えるとエラーが発生します。
- dashscope CLI
CosyVoice
SDK は、次の合成モードをサポートしています:
- ノンストリーミング呼び出し:ブロッキング型で、完全なテキストを一度に送信し、完全な音声を直接返します。短いテキストの音声合成シナリオに適しています。
- 単方向ストリーミング呼び出し:ノンブロッキング型で、完全なテキストを一度に送信し、
streamが返す音声チャンクを反復処理してデータを受信します。リアルタイム性の要件が高い短いテキストの音声合成シナリオに適しています。 - 双方向ストリーミング呼び出し:ノンブロッキング型で、テキストセグメントを複数回に分けて送信し、セッションの
audio_chunks()/events()の反復処理で増分合成された音声ストリームをリアルタイムに受信します。リアルタイム性の要件が高い長いテキストの音声合成シナリオに適しています。
- ノンストリーミング
- 単方向ストリーミング
- 双方向ストリーミング
DashScopeError 例外がトリガーされます。リクエストパラメーター
Qwen-Audio-TTS
以下のパラメーターは 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。ストリーミング出力モードでのみ利用可能です。クローン音声がサポートされています。対応するシステム音声については、「Qwen-Audio-TTS 音声リスト」をご参照ください。word_timestamp_enabled は parameters 辞書で設定します: |
seed | int | いいえ | 合成結果の変動を制御するためのランダムシードです。モデルのバージョン、テキスト、音声、その他のパラメーターが変わらない場合、同じシードを使用すると同一の結果が得られます。デフォルト値:0。有効な値:[0, 65535]。 |
language_hints | list[str] | いいえ | qwen-audio-3.1-tts-flash の多言語・方言対応音声では、このパラメーターで言語や方言を指定できます。詳しくは 多言語・方言対応音声の設定方法 を参照してください。
有効な値
|
instruction | str | いいえ | 方言、感情、話し方のスタイルなど、合成の特性を制御します。使用方法の詳細については、「指示コントロール」をご参照ください。 |
enable_aigc_tag | bool | いいえ | 生成された音声に AIGC ウォーターマークを埋め込むかどうかを指定します。true に設定すると、対応するフォーマット (wav/mp3/opus) の音声ファイルにウォーターマークが埋め込まれます。デフォルト値:false。enable_aigc_tag、aigc_propagator、aigc_propagate_id は parameters 辞書で設定します: |
aigc_propagator | str | いいえ | AIGC ウォーターマークの ContentPropagator フィールドを設定し、コンテンツの伝播者を識別します。enable_aigc_tag が true の場合にのみ有効になります。デフォルト値:Alibaba Cloud の UID。parameters 辞書で設定します。設定例については enable_aigc_tag をご参照ください。 |
aigc_propagate_id | str | いいえ | AIGC ウォーターマークの PropagateID フィールドを設定し、特定の伝播アクションを一意に識別します。enable_aigc_tag が true の場合にのみ有効になります。デフォルト値:現在の音声合成リクエストのリクエスト ID。parameters 辞書で設定します。設定例については enable_aigc_tag をご参照ください。 |
hot_fix | dict | いいえ | 合成前に適用される発音修正とテキスト置換を設定します。パラメーター:
|
CosyVoice
以下のパラメーターは 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 ディクショナリで設定します: |
API リファレンス
Qwen-Audio-TTS
最新のリファレンスは Qwen-Audio-TTS Python SDK をご参照ください。
コアリソース(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キーを含む)です。最新のリクエストのリクエスト ID はsession.last_responseのheaderから取得でき、トラブルシューティングやログの関連付けに役立ちます。
セッションとイベント反復
ストリーミング合成はコールバックインターフェイスを使用しなくなりました。音声とサーバーイベントは、セッションの反復メソッドで受信します。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 に直接アクセスしてください。
エラー処理
合成中にエラーが発生すると、WebSocket 層は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 が有効な場合にタイムスタンプ情報を含む) が含まれます。 |
CosyVoice
最新のリファレンスは CosyVoice Python SDK をご参照ください。
コアリソース(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から取得でき、問題の切り分けやログとの関連付けに使用できます。
会話とイベント反復
ストリーミング合成ではコールバックインターフェイスを使用しなくなりました:音声とサーバーイベントはセッションの反復メソッドで受信します。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 が有効な場合にタイムスタンプ情報を含む) が含まれます。 |