DashScope Python SDK を使用して、非ストリーミング、一方向ストリーミング、または双方向ストリーミングモードで、Qwen-Audio-TTS のリアルタイム音声合成をアプリケーションに統合します。
最新のリファレンスは Qwen-Audio-TTS Python SDK をご参照ください。
サービスエンドポイント
SDK のサービスエンドポイントは、Client の構築パラメーター workspace/region で決まります(下記のアドレスに対応し、WorkspaceId を含みます)。別のリージョンに切り替えるには、Client の構築パラメーターを対象リージョンの値に変更してください。
Singapore
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
{WorkspaceId} を実際のワークスペース ID に置き換えます。
China (Beijing)
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
{WorkspaceId} を実際のワークスペース ID に置き換えます。
ImportantAlibaba Cloud Model Studio は、China (Beijing) および Singapore リージョン向けに、ワークスペース専用ドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。新しいドメインへの移行を推奨します:
- China (Beijing):
dashscope.aliyuncs.comから{WorkspaceId}.cn-beijing.maas.aliyuncs.comへ - Singapore:
dashscope-intl.aliyuncs.comから{WorkspaceId}.ap-southeast-1.maas.aliyuncs.comへ
コアリソース(client.audio.tts)
リソースパス: client.audio.tts
機能: WebSocket ベースの音声合成です。一括合成(synthesize)、ストリーミング合成(stream)、双方向ストリーミングセッション(connect)の 3 つの呼び出しモードを提供します。
呼び出し入口
# 一括合成:完全なオーディオを bytes として返します
audio = client.audio.tts.synthesize(
text, # text は必須(位置引数)
model="qwen-audio-3.0-tts-flash", # 音声が属するモデル
voice="longanhuan_v3.6", # 音声
format="mp3", # 音声のエンコードフォーマット、デフォルト "mp3"
sample_rate=22050, # サンプリングレート、デフォルト 22050
)
# ストリーミング合成:音声の bytes チャンクを 1 つずつ返します(受信しながら書き込みまたは再生します)
for chunk in client.audio.tts.stream(text, model=..., voice=...):
...
# 双方向ストリーミングセッション:テキストを分割して送信します。with コンテキストに入ると接続が自動的に確立されます
with client.audio.tts.connect(model=..., voice=...) as session:
session.send_text(text) # 複数回呼び出してテキストを追加できます
session.stop() # サーバーに入力が完了したことを通知します
for chunk in session.audio_chunks():
...
synthesize() - 非ストリーミング
メソッドシグネチャ:
def synthesize(self, text: str, *, model: str,
voice: str, format: str = "mp3",
sample_rate: int = 22050, volume: int = None,
rate: float = None, pitch: float = None,
language_hints: list = None, enable_ssml: bool = None,
parameters: Dict = None, ...) -> bytes
パラメーター:
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
text | str | はい | 合成する完全なテキストです。最大長は 20,000 文字です。 |
戻り値: 完全なオーディオデータを含む bytes。
説明: このブロッキング呼び出しは合成の完了を待機し、完全なオーディオデータを一度に返します。リアルタイム伝送が不要な短いテキストに最も適しています。synthesize と stream は呼び出しごとに独立したセッションを作成するため、インスタンスを再利用する必要はありません。
stream() - ストリーミング
メソッドシグネチャ:
def stream(self, text: str, *, model: str, voice: str,
format: str = "mp3", sample_rate: int = 22050, ...) -> Iterator[bytes]
パラメーター:
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
text | str | はい | 合成する完全なテキストです。最大長は 20,000 文字です。 |
戻り値: チャンク単位で返されるオーディオデータを含む Iterator[bytes]。
説明: ストリーミング合成は完全なテキストを一度に送信し、オーディオをチャンク単位(Iterator[bytes])で返します。低レイテンシーが求められる短いテキストの音声合成に最適です。テキストを分割して送信するには、双方向ストリーミングセッション(connect)を使用してください。
send_text() - ストリーミング入力(セッションメソッド)
双方向ストリーミングセッション(client.audio.tts.connect(...))内でテキストを分割して送信します。
メソッドシグネチャ:
def send_text(self, text: str) -> None
パラメーター: text は今回合成するテキストセグメントです。send_text は複数回呼び出してテキストを追加できます。1 回あたりの最大値は 20,000 文字、累積最大値は 200,000 文字です。テキストの送信とオーディオの受信は並行して実行する必要があります(audio_chunks()/events() および stop と併用してください)。
stop() - ストリーミング入力の終了(セッションメソッド)
メソッドシグネチャ:
def stop(self) -> None
説明: すべてのテキストが送信されたことをサーバーに通知します。この呼び出しは現在のスレッドをブロックしません。受信スレッドは、残りのテキストが合成されてすべてのオーディオデータが返されるまで、audio_chunks()/events() を消費し続ける必要があります。このメソッドを呼び出さない場合、末尾のテキストが音声に変換されない可能性があります。
cancel() - ストリーミング合成のキャンセル(セッションメソッド)
メソッドシグネチャ:
def cancel(self) -> None
説明: 現在のストリーミング音声合成のターンをキャンセルします。このメソッドを呼び出すと、SDK は現在のタスクを直ちに終了します。キャンセル後、セッションはテキストを送信できなくなります。合成を続行するには、新しいセッションを作成してください。
セッションのメトリクスと応答(セッション属性)
session.first_package_delay
session.usage
session.last_response
first_package_delay:float。テキスト送信から最初のオーディオチャンク受信までの遅延(ミリ秒)です。合成完了後に読み取ります。usage:dict。最新の合成タスクの使用量情報です。last_response:dict。最新の合成タスクの応答メッセージ(header/payloadキーを含む)です。最新のリクエストのリクエスト 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 などのフォーマットをサポートします。サンプリングレートは |
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]。
|
word_timestamp_enabled | bool | いいえ | 単語レベルのタイムスタンプを有効にするかどうかを指定します。 デフォルト値:false。 ストリーミング出力モードでのみ利用可能です。クローン音声がサポートされています。対応するシステム音声については、「Qwen-Audio-TTS 音声リスト」をご参照ください。
|
seed | int | いいえ | 合成結果の変動を制御するためのランダムシードです。モデルのバージョン、テキスト、音声、その他のパラメーターが変わらない場合、同じシードを使用すると同一の結果が得られます。 デフォルト値:0。 有効な値:[0, 65535]。 |
language_hints | list[str] | いいえ | Noteqwen-audio-3.1-tts-flash の多言語・方言対応音声では、このパラメーターで言語や方言を指定できます。詳しくは 多言語・方言対応音声の設定方法 を参照してください。 出力品質を向上させるために、音声合成のターゲット言語を指定します。 数字の発音、略語の展開、記号の読み上げ、または少数言語の合成が期待どおりでない場合に、このパラメーターを使用します。例:
有効な値
Note
|
instruction | str | いいえ | 方言、感情、話し方のスタイルなど、合成の特性を制御します。 使用方法の詳細については、「指示コントロール」をご参照ください。 |
enable_aigc_tag | bool | いいえ | 生成された音声に AIGC ウォーターマークを埋め込むかどうかを指定します。true に設定すると、対応するフォーマット (wav/mp3/opus) の音声ファイルにウォーターマークが埋め込まれます。 デフォルト値:false。
|
aigc_propagator | str | いいえ | AIGC ウォーターマークの ContentPropagator フィールドを設定し、コンテンツの伝播者を識別します。enable_aigc_tag が true の場合にのみ有効になります。デフォルト値:Alibaba Cloud の UID。
|
aigc_propagate_id | str | いいえ | AIGC ウォーターマークの PropagateID フィールドを設定し、特定の伝播アクションを一意に識別します。enable_aigc_tag が true の場合にのみ有効になります。デフォルト値:現在の音声合成リクエストのリクエスト ID。
|
hot_fix | dict | いいえ | 合成前に適用される発音修正とテキスト置換を設定します。 パラメーター:
設定例: |
セッションとイベント反復
ストリーミング合成はコールバックインターフェイスを使用しなくなりました。音声とサーバーイベントは、セッションの反復メソッドで受信します。stream()/synthesize() はセッション管理を必要としません。双方向ストリーミングセッション(client.audio.tts.connect(...))のライフサイクルは次のとおりです:with コンテキストに入ると接続が自動的に開かれる → send_text() を複数回呼び出す → stop() → 残りの結果をすべて読み取る → コンテキストの退出時に接続が自動的に閉じられる。
audio_chunks() - 音声データの反復
メソッドシグネチャ:
def audio_chunks(self) -> Iterator[bytes]
戻り値: チャンク単位で返されるバイナリ音声データを含む Iterator[bytes]。format パラメーターで指定されたフォーマットです。
説明: 受信スレッドで反復処理して、音声データをチャンク単位で受信します。合成中は複数のチャンクが生成されます。データをファイルに書き込むか、再生デバイスに送信してください。セッションごとに許可される events() または audio_chunks() のリーダーは 1 つだけです。
events() - サーバーイベントの反復
メソッドシグネチャ:
def events(self) -> Generator[Union[Dict, bytes], None, None]
戻り値: サーバー応答イベント(dict。header(リクエスト情報)と payload(出力情報)を含む)と音声の bytes の両方を返します。payload.output にはイベントタイプ、元テキストなどの詳細が含まれます。events() イベントの output フィールドをご参照ください。
説明: 受信スレッドでサーバー応答を反復処理します。合成イベントの出力情報(イベントタイプ、元テキスト、文情報)が含まれます。詳細を取得するには payload.output に直接アクセスしてください。
エラー処理
合成中にエラーが発生すると、WebSocket 層は DashScopeError 例外をスローし、例外のスロー後に接続は自動的に閉じられます。送信側または受信側で try/except を使用してエラーを捕捉し、記録してトラブルシューティングに使用してください:
from dashscope.v2 import DashScopeError
try:
...
except DashScopeError as e:
print(e.code, e.message, e.request_id)
セッションのライフサイクル
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 が有効な場合にタイムスタンプ情報を含む) が含まれます。 |
メッセージ例:
{
"header": {
"task_id": "xxx",
"event": "result-generated",
"attributes": {}
},
"payload": {
"output": {
"type": "sentence-begin",
"original_text": "How is the weather today?",
"sentence": {
"index": 0,
"words": []
}
}
}
}
解析例:
def handle_event(event):
output = (event.get('payload') or {}).get('output') or {}
event_type = output.get('type', '')
original_text = output.get('original_text', '')
if event_type:
print(f'Event type: {event_type}, original text: {original_text}')
コード例
SDK は、次の合成モードをサポートしています:
- 非ストリーミング: 完全なテキストを一度に送信し、完全な音声を直接返すブロッキング呼び出しです。短いテキストの音声合成に最適です。
- 一方向ストリーミング: 完全なテキストを一度に送信し、
streamが返すオーディオチャンクを反復処理して音声データを受信するノンブロッキング呼び出しです。低レイテンシーが求められる短いテキストのシナリオに最適です。 - 双方向ストリーミング: テキストを複数のセグメントで送信し、セッションの
audio_chunks()/events()を反復処理して、リアルタイムで増分合成された音声ストリームを受信するノンブロッキング呼び出しです。低レイテンシーが求められる長いテキストのシナリオに最適です。
非ストリーミング
1 回の呼び出しで送信されるテキストは 20,000 文字を超えてはなりません。この制限を超えるとエラーが発生します。
Importantsynthesize と stream は呼び出しごとに独立したセッションを作成するため、インスタンスを再利用する必要はありません。
# coding=utf-8
import os
import dashscope
# API キーは、シンガポールリージョンと北京リージョンで異なります。API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: api_key="sk-xxx"
# 以下はシンガポール (ap-southeast-1) リージョンの設定です。呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# モデル
model = "qwen-audio-3.0-tts-flash"
# 音声
voice = "longanhuan_v3.6"
# 合成するテキストを送信し、バイナリオーディオを取得します
audio = client.audio.tts.synthesize("How is the weather today?", model=model, voice=voice)
# 音声をローカルファイルに保存します
with open('output.mp3', 'wb') as f:
f.write(audio)
dashscope CLI
dashscope コマンドラインから呼び出します。
export DASHSCOPE_API_KEY="your-api-key"
# {WorkspaceId} をワークスペース ID に、ap-southeast-1 を対象リージョン (例: us-east-1、eu-central-1) に置き換えます
export DASHSCOPE_HTTP_BASE_URL="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
dashscope speech-synthesis create -m qwen-audio-3.0-tts-flash -t "Hello world" --voice longanhuan_v3.6
ImportantSDK Expert インタラクティブアシスタントは、自然言語で同じ開発タスクやトラブルシューティングを行えます。「
DashScope SDK Expert」をご参照ください。地域の完全な一覧については、「Base URL 一覧」をご参照ください。
一方向ストリーミング
1 回の呼び出しで送信されるテキストは 20,000 文字を超えてはなりません。この制限を超えるとエラーが発生します。
Importantsynthesize と stream は呼び出しごとに独立したセッションを作成するため、インスタンスを再利用する必要はありません。
# coding=utf-8
import os
from datetime import datetime
import dashscope
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
# API キーは、シンガポールリージョンと北京リージョンで異なります。API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: api_key="sk-xxx"
# 以下はシンガポール (ap-southeast-1) リージョンの設定です。呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# モデル
model = "qwen-audio-3.0-tts-flash"
# 音声
voice = "longanhuan_v3.6"
# 完全なテキストを一度に送信し、バイナリオーディオをチャンク単位で受信します
with open("output.mp3", "wb") as f:
for chunk in client.audio.tts.stream("How is the weather today?", model=model, voice=voice):
print(get_timestamp() + " Binary audio length: " + str(len(chunk)))
f.write(chunk)
print("Speech synthesis completed, all results received: " + get_timestamp())
双方向ストリーミング
1 回の呼び出しで送信されるテキストは 20,000 文字を超えてはなりません。累積テキストは 200,000 文字を超えてはなりません。
-
ストリーミング入力中、
send_textを複数回呼び出して、テキストセグメントを順次送信します。サーバーは受信したテキストに対して自動的に文分割を実行します:- 完全な文は直ちに合成されます
- 不完全な文は完全になるまでバッファリングされます
stopが呼び出されると、サーバーは受信した未処理のすべてのテキスト (不完全な文を含む) を強制的に合成します。 -
テキストセグメント間の間隔は 23 秒を超えてはなりません。超えた場合、「request timeout after 23 seconds」という例外が発生します。
送信するテキストがない場合は、速やかに
stopを呼び出してタスクを終了してください。Important常に
stopを呼び出してください。呼び出さない場合、末尾のテキストが音声に変換されない可能性があります。サーバーは 23 秒のタイムアウトを強制します。この値はクライアント側では変更できません。
# coding=utf-8
#
# pyaudio のインストール手順:
# macOS の場合、次のコマンドを実行します:
# brew install portaudio
# pip install pyaudio
# Debian/Ubuntu の場合、次のコマンドを実行します:
# sudo apt-get install python-pyaudio python3-pyaudio
# または
# pip install pyaudio
# CentOS の場合、次のコマンドを実行します:
# sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# Microsoft Windows の場合、次のコマンドを実行します:
# python -m pip install pyaudio
import os
import time
import pyaudio
from concurrent.futures import ThreadPoolExecutor
import dashscope
from datetime import datetime
def get_timestamp():
now = datetime.now()
formatted_timestamp = now.strftime("[%Y-%m-%d %H:%M:%S.%f]")
return formatted_timestamp
# API キーは、シンガポールリージョンと北京リージョンで異なります。API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: api_key="sk-xxx"
# 以下はシンガポール (ap-southeast-1) リージョンの設定です。呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
client = dashscope.Client(
api_key=os.environ.get('DASHSCOPE_API_KEY'),
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
# モデル
model = "qwen-audio-3.0-tts-flash"
# 音声
voice = "longanhuan_v3.6"
test_text = [
"Streaming text-to-speech SDK,",
"converts input text",
"into binary audio data.",
"Compared with non-streaming speech synthesis,",
"streaming synthesis offers better real-time performance.",
"Users hear near-synchronous audio output while typing,",
"greatly improving interaction experience",
"and reducing wait time.",
"Ideal for large language model (LLM) integration,",
"where text is streamed for speech synthesis.",
]
# 双方向ストリーミング合成セッションを作成します:with コンテキストに入ると接続が自動的に確立されます
with client.audio.tts.connect(
model=model,
voice=voice,
format="pcm",
sample_rate=22050,
) as session:
# プレーヤーを初期化します
player = pyaudio.PyAudio()
stream = player.open(format=pyaudio.paInt16, channels=1, rate=22050, output=True)
# 受信スレッド:音声データを反復処理し、リアルタイムで再生します
def receive_audio():
for chunk in session.audio_chunks():
print(get_timestamp() + " Binary audio length: " + str(len(chunk)))
stream.write(chunk)
with ThreadPoolExecutor(max_workers=1) as pool:
receiver = pool.submit(receive_audio)
# ストリーミング合成のためにテキストを送信します
for text in test_text:
session.send_text(text)
time.sleep(0.1)
# ストリーミング音声合成を終了します
session.stop()
receiver.result()
print("Speech synthesis completed, all results received: " + get_timestamp())
# プレーヤーを停止します
stream.stop_stream()
stream.close()
player.terminate()
# 最初のテキスト送信では WebSocket 接続を確立する必要があるため、初回パケットレイテンシーには接続確立時間が含まれます
print('[Metric] first packet latency: {} ms'.format(session.first_package_delay))