Skip to main content

Qwen-Audio-TTS Python SDK

DashScope Python SDK を使用して、非ストリーミング、一方向ストリーミング、または双方向ストリーミングモードで、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 に置き換えます。
Alibaba 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
パラメーター:
パラメーター型必須説明
textstrはい合成する完全なテキストです。最大長は 20,000 文字です。
戻り値: 完全なオーディオデータを含む bytes。 説明: このブロッキング呼び出しは合成の完了を待機し、完全なオーディオデータを一度に返します。リアルタイム伝送が不要な短いテキストに最も適しています。synthesize と stream は呼び出しごとに独立したセッションを作成するため、インスタンスを再利用する必要はありません。

stream() - ストリーミング

メソッドシグネチャ:
def stream(self, text: str, *, model: str, voice: str,
           format: str = "mp3", sample_rate: int = 22050, ...) -> Iterator[bytes]
パラメーター:
パラメーター型必須説明
textstrはい合成する完全なテキストです。最大長は 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 辞書で渡します)。
パラメーター型必須説明
modelstrはいモデル名です。
voicestrはい音声合成に使用する音声。
  • システム音声: 「Qwen-Audio-TTS 音声リスト」をご参照ください。
  • クローン音声: 音声クローニングによって作成されたカスタム音声
  • カスタム音声: 音声デザインによって作成されたカスタム音声
formatstrいいえ音声のエンコードフォーマットです。デフォルト値:mp3。mp3、wav、pcm などのフォーマットをサポートします。サンプリングレートは sample_rate パラメーターで設定し、デフォルト値は 22050 です。
volumeintいいえ音量です。デフォルト値:50。有効な値:[0, 100]。
ratefloatいいえ話速です。デフォルト値:1.0。有効な値:[0.5, 2.0]。
pitchfloatいいえピッチです。デフォルト値:1.0。有効な値:[0.5, 2.0]。
bit_rateintいいえ音声のビットレート (kbps) です。音声フォーマットが mp3 または opus の場合、bit_rate でビットレートを調整します。デフォルト値:32。有効な値:[6, 510]。bit_rate は parameters 辞書で設定します:
audio = client.audio.tts.synthesize(
    "Text to synthesize",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={"bit_rate": 128},
)
word_timestamp_enabledboolいいえ単語レベルのタイムスタンプを有効にするかどうかを指定します。デフォルト値:false。ストリーミング出力モードでのみ利用可能です。クローン音声がサポートされています。対応するシステム音声については、「Qwen-Audio-TTS 音声リスト」をご参照ください。word_timestamp_enabled は parameters 辞書で設定します:
audio = client.audio.tts.stream(
    "Text to synthesize",
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice",  # 単語レベルのタイムスタンプをサポートするシステム音声またはクローン音声
    parameters={"word_timestamp_enabled": True},
)
seedintいいえ合成結果の変動を制御するためのランダムシードです。モデルのバージョン、テキスト、音声、その他のパラメーターが変わらない場合、同じシードを使用すると同一の結果が得られます。デフォルト値:0。有効な値:[0, 65535]。
language_hintslist[str]いいえ
  • このパラメーターは配列ですが、現在のバージョンでは最初の要素のみが処理されます。単一の値を渡してください。
  • このパラメーターは音声合成のターゲット言語を指定します。これは、音声クローニングで使用される音声サンプルの言語とは無関係です。クローニングタスクのソース言語を設定するには、音声クローニング API リファレンスをご参照ください。
出力品質を向上させるために、音声合成のターゲット言語を指定します。数字の発音、略語の展開、記号の読み上げ、または少数言語の合成が期待どおりでない場合に、このパラメーターを使用します。例:
  • 予期しない数字の発音:「hello, this is 110」が、期待される中国語の発音ではなく「hello, this is one zero」と読まれる場合
  • 不正確な記号の発音:「@」が「at」ではなく、中国語の同等語で読まれる場合
  • 少数言語の合成品質が低く、不自然な結果になる場合
  • zh:中国語
  • en:英語
  • fr:フランス語
  • de:ドイツ語
  • ja:日本語
  • ko:韓国語
  • ru:ロシア語
  • pt:ポルトガル語
  • th:タイ語
  • id:インドネシア語
  • vi:ベトナム語
  • es:スペイン語
  • it:イタリア語
  • ms:マレーシア語
  • fil:フィリピン語
  • ar:アラビア語
  • other:その他の言語(qwen-audio-3.1-tts-flash でサポート) ブルガリア語、オランダ語、ハンガリー語、ルーマニア語、デンマーク語、クロアチア語、ギリシャ語、チェコ語、ノルウェー語、スウェーデン語、ヒンディー語、スロバキア語、フィンランド語、ウルドゥー語、セルビア語、スペイン語 (メキシコ)、リトアニア語、ラトビア語、トルコ語、ペルシア語、ヘブライ語、モンゴル語、スロベニア語、アゼルバイジャン語、ポーランド語、カタロニア語、クメール語、ポルトガル語 (ブラジル)、ラオ語、ジョージア語、アフリカーンス語、ネパール語、ベラルーシ語、マラヤーラム語、ルクセンブルク語、アルバニア語、タミル語、シンハラ語、テルグ語、エストニア語、セブアノ語、ボスニア語、ミャンマー語、アルメニア語、ラテン語、アイスランド語、マルタ語、スワヒリ語、カザフ語、セーシェル・クレオール語、ウクライナ語。
instructionstrいいえ方言、感情、話し方のスタイルなど、合成の特性を制御します。使用方法の詳細については、「指示コントロール」をご参照ください。
enable_aigc_tagboolいいえ生成された音声に AIGC ウォーターマークを埋め込むかどうかを指定します。true に設定すると、対応するフォーマット (wav/mp3/opus) の音声ファイルにウォーターマークが埋め込まれます。デフォルト値:false。enable_aigc_tag、aigc_propagator、aigc_propagate_id は parameters 辞書で設定します:
audio = client.audio.tts.synthesize(
    "Text to synthesize",
    model="qwen-audio-3.0-tts-flash",
    voice="longanhuan_v3.6",
    parameters={
        "enable_aigc_tag": True,
        "aigc_propagator": "your_propagator",
        "aigc_propagate_id": "your_propagate_id"
    },
)
aigc_propagatorstrいいえAIGC ウォーターマークの ContentPropagator フィールドを設定し、コンテンツの伝播者を識別します。enable_aigc_tag が true の場合にのみ有効になります。デフォルト値:Alibaba Cloud の UID。parameters 辞書で設定します。設定例については enable_aigc_tag をご参照ください。
aigc_propagate_idstrいいえAIGC ウォーターマークの PropagateID フィールドを設定し、特定の伝播アクションを一意に識別します。enable_aigc_tag が true の場合にのみ有効になります。デフォルト値:現在の音声合成リクエストのリクエスト ID。parameters 辞書で設定します。設定例については enable_aigc_tag をご参照ください。
hot_fixdictいいえ合成前に適用される発音修正とテキスト置換を設定します。パラメーター:
  • pronunciation:カスタム発音。単語に拼音注釈を指定し、デフォルトの発音が不正確な場合に修正します。
  • replace:テキスト置換。合成前に特定の単語をターゲットテキストに置き換えます。置換後のテキストが合成の実際の入力として使用されます。
設定例:
audio = client.audio.tts.synthesize(
    "Text to synthesize",
    model="qwen-audio-3.0-tts-flash",
    voice="your_voice_id", # 音声
    parameters={
        "hot_fix": {
            "pronunciation": [{"weather": "tian1 qi4"}],
            "replace": [{"today": "gold day"}]
        }
    },
)

セッションとイベント反復

ストリーミング合成はコールバックインターフェイスを使用しなくなりました。音声とサーバーイベントは、セッションの反復メソッドで受信します。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 フィールドの構造は次のとおりです。
フィールド型説明
typestrイベントタイプ。値は、 sentence-begin (文の合成開始)、 sentence-synthesis (文の合成進行中)、または sentence-end (文の合成完了) のいずれかです。
original_textstr現在の文の元のテキスト。 sentence-begin および sentence-end イベントで返されます。
sentencedict文情報。 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 文字を超えてはなりません。この制限を超えるとエラーが発生します。
synthesize と 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
SDK Expert インタラクティブアシスタントは、自然言語で同じ開発タスクやトラブルシューティングを行えます。「DashScope SDK Expert」をご参照ください。
地域の完全な一覧については、「Base URL 一覧」をご参照ください。