Python SDK で Qwen リアルタイム音声合成を呼び出す - Model Studio - Alibaba Cloud - Alibaba Cloud Model Studio

このトピックでは、DashScope Python SDK を使用してリアルタイム音声合成 (Qwen)を呼び出す際の主要インターフェイスおよびリクエストパラメーターについて説明します。

ユーザーガイド：モデルの概要および選定に関する推奨事項については、「リアルタイム音声合成 – Qwen」または「音声合成 – Qwen」をご参照ください。

重要

シンガポールリージョン向けのレガシードメイン https://dashscope-intl.aliyuncs.com はまもなく非推奨になります。できるだけ早く新しいドメイン https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com に移行してください。

前提条件

DashScope Python SDK 1.25.11 以降が必要です。

クイックスタート

サーバーコミットモード

import os
import base64
import threading
import time
import dashscope
from dashscope.audio.qwen_tts_realtime import *


qwen_tts_realtime: QwenTtsRealtime = None
text_to_synthesize = [
    'Right? I love supermarkets like this.',
    'Especially during Chinese New Year,',
    'I go shopping at supermarkets.',
    'And I feel',
    'absolutely thrilled!',
    'I want to buy so many things!'
]

DO_VIDEO_TEST = False

def init_dashscope_api_key():
    """
        DashScope API キーを設定します。詳細情報:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    # API キーはシンガポールリージョンと北京リージョンで異なります。API キーの取得方法: https://www.alibabacloud.com/help/ja/model-studio/get-api-key
    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # 環境変数 DASHSCOPE_API_KEY から API キーをロード
    else:
        dashscope.api_key = 'your-dashscope-api-key'  # API キーを手動で設定



class MyCallback(QwenTtsRealtimeCallback):
    def __init__(self):
        self.complete_event = threading.Event()
        self.file = open('result_24k.pcm', 'wb')

    def on_open(self) -> None:
        print('connection opened, init player')

    def on_close(self, close_status_code, close_msg) -> None:
        self.file.close()
        print('connection closed with code: {}, msg: {}, destroy player'.format(close_status_code, close_msg))

    def on_event(self, response: str) -> None:
        try:
            global qwen_tts_realtime
            type = response['type']
            if 'session.created' == type:
                print('start session: {}'.format(response['session']['id']))
            if 'response.audio.delta' == type:
                recv_audio_b64 = response['delta']
                self.file.write(base64.b64decode(recv_audio_b64))
            if 'response.done' == type:
                print(f'response {qwen_tts_realtime.get_last_response_id()} done')
            if 'session.finished' == type:
                print('session finished')
                self.complete_event.set()
        except Exception as e:
            print('[Error] {}'.format(e))
            return

    def wait_for_finished(self):
        self.complete_event.wait()


if __name__  == '__main__':
    init_dashscope_api_key()

    print('Initializing ...')

    callback = MyCallback()

    qwen_tts_realtime = QwenTtsRealtime(
        # 命令制御を使用する場合は、モデルを qwen3-tts-instruct-flash-realtime に置き換えます
        model='qwen3-tts-flash-realtime',
        callback=callback,
        # この URL はシンガポールリージョン用です。中国 (北京) リージョンを使用する場合は、次の URL に置き換えてください: wss://dashscope.aliyuncs.com/api-ws/v1/realtime
        url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime'
        )

    qwen_tts_realtime.connect()
    qwen_tts_realtime.update_session(
        voice = 'Cherry',
        response_format = AudioFormat.PCM_24000HZ_MONO_16BIT,
        # 命令制御を使用する場合は、以下の行のコメントを解除し、モデルを qwen3-tts-instruct-flash-realtime に置き換えてください
        # instructions='Speak quickly with a rising intonation, suitable for introducing fashion products.',
        # optimize_instructions=True,
        mode = 'server_commit'        
    )
    for text_chunk in text_to_synthesize:
        print(f'send text: {text_chunk}')
        qwen_tts_realtime.append_text(text_chunk)
        time.sleep(0.1)
    qwen_tts_realtime.finish()
    callback.wait_for_finished()
    print('[Metric] session: {}, first audio delay: {}'.format(
                    qwen_tts_realtime.get_session_id(), 
                    qwen_tts_realtime.get_first_audio_delay(),
                    ))

コミットモード

import base64
import os
import threading
import dashscope
from dashscope.audio.qwen_tts_realtime import *


qwen_tts_realtime: QwenTtsRealtime = None
text_to_synthesize = [
    'This is the first sentence.',
    'This is the second sentence.',
    'This is the third sentence.',
]

DO_VIDEO_TEST = False

def init_dashscope_api_key():
    """
        DashScope API キーを設定します。詳細情報:
        https://github.com/aliyun/alibabacloud-bailian-speech-demo/blob/master/PREREQUISITES.md
    """

    # API キーはシンガポールリージョンと北京リージョンで異なります。API キーの取得方法: https://www.alibabacloud.com/help/ja/model-studio/get-api-key
    if 'DASHSCOPE_API_KEY' in os.environ:
        dashscope.api_key = os.environ[
            'DASHSCOPE_API_KEY']  # 環境変数 DASHSCOPE_API_KEY から API キーをロード
    else:
        dashscope.api_key = 'your-dashscope-api-key'  # API キーを手動で設定



class MyCallback(QwenTtsRealtimeCallback):
    def __init__(self):
        super().__init__()
        self.response_counter = 0
        self.complete_event = threading.Event()
        self.file = open(f'result_{self.response_counter}_24k.pcm', 'wb')

    def reset_event(self):
        self.response_counter += 1
        self.file = open(f'result_{self.response_counter}_24k.pcm', 'wb')
        self.complete_event = threading.Event()

    def on_open(self) -> None:
        print('connection opened, init player')

    def on_close(self, close_status_code, close_msg) -> None:
        print('connection closed with code: {}, msg: {}, destroy player'.format(close_status_code, close_msg))

    def on_event(self, response: str) -> None:
        try:
            global qwen_tts_realtime
            type = response['type']
            if 'session.created' == type:
                print('start session: {}'.format(response['session']['id']))
            if 'response.audio.delta' == type:
                recv_audio_b64 = response['delta']
                self.file.write(base64.b64decode(recv_audio_b64))
            if 'response.done' == type:
                print(f'response {qwen_tts_realtime.get_last_response_id()} done')
                self.complete_event.set()
                self.file.close()
            if 'session.finished' == type:
                print('session finished')
                self.complete_event.set()
        except Exception as e:
            print('[Error] {}'.format(e))
            return

    def wait_for_response_done(self):
        self.complete_event.wait()


if __name__  == '__main__':
    init_dashscope_api_key()

    print('Initializing ...')

    callback = MyCallback()

    qwen_tts_realtime = QwenTtsRealtime(
        # 命令制御を使用する場合は、モデルを qwen3-tts-instruct-flash-realtime に置き換えます
        model='qwen3-tts-flash-realtime',
        callback=callback, 
        # この URL はシンガポールリージョン用です。中国 (北京) リージョンを使用する場合は、次の URL に置き換えてください: wss://dashscope.aliyuncs.com/api-ws/v1/realtime
        url='wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime'
        )

    qwen_tts_realtime.connect()
    qwen_tts_realtime.update_session(
        voice = 'Cherry',
        response_format = AudioFormat.PCM_24000HZ_MONO_16BIT,
        # 命令制御を使用する場合は、以下の行のコメントを解除し、モデルを qwen3-tts-instruct-flash-realtime に置き換えてください
        # instructions='Speak quickly with a rising intonation, suitable for introducing fashion products.',
        # optimize_instructions=True,
        mode = 'commit'        
    )
    print(f'send text: {text_to_synthesize[0]}')
    qwen_tts_realtime.append_text(text_to_synthesize[0])
    qwen_tts_realtime.commit()
    callback.wait_for_response_done()
    callback.reset_event()
    
    print(f'send text: {text_to_synthesize[1]}')
    qwen_tts_realtime.append_text(text_to_synthesize[1])
    qwen_tts_realtime.commit()
    callback.wait_for_response_done()
    callback.reset_event()

    print(f'send text: {text_to_synthesize[2]}')
    qwen_tts_realtime.append_text(text_to_synthesize[2])
    qwen_tts_realtime.commit()
    callback.wait_for_response_done()
    
    qwen_tts_realtime.finish()
    print('[Metric] session: {}, first audio delay: {}'.format(
                    qwen_tts_realtime.get_session_id(), 
                    qwen_tts_realtime.get_first_audio_delay(),
                    ))

その他のサンプルコードをダウンロードするには、GitHub をご確認ください。

リクエストパラメーター

次のパラメーターを QwenTtsRealtime コンストラクターで設定します。

パラメーター	型	必須	説明
model	str	はい	モデル名（サポートされるモデルを参照）。
url	str	はい	中国 (北京)：`wss://dashscope.aliyuncs.com/api-ws/v1/realtime` シンガポール：`wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime` `WorkspaceId` は、実際のワークスペース IDに置き換えてください。

次のパラメーターは update_session を使用して設定します。

パラメーター	型	必須	説明
voice	str	はい	音声合成に使用する音声です。詳細については、「サポートされる音声」をご参照ください。システム音声とカスタム音声がサポートされています。システム音声：Qwen3-TTS-Instruct-Flash-Realtime、Qwen3-TTS-Flash-Realtime、および Qwen-TTS-Realtime モデルシリーズでのみ利用可能です。音声サンプルについては、「サポートされる音声」をご参照ください。カスタム音声 Voice Cloning (Qwen) 機能でカスタマイズされた音声：Qwen3-TTS-VC-Realtime モデルシリーズでのみ利用可能です。 Voice Design (Qwen) 機能でカスタマイズされた音声：Qwen3-TTS-VD-Realtime モデルシリーズでのみ利用可能です。
language_type	str	いいえ	合成オーディオの言語を指定します。デフォルト値は `Auto` です。 `Auto`：テキストの言語が不明な場合や複数の言語が含まれる場合に使用します。モデルはテキスト内の異なる言語セグメントに対して自動的に発音をマッチングしますが、完全な精度を保証するものではありません。特定の言語：単一言語のテキストに使用します。言語を指定することで合成品質が大幅に向上し、通常は `Auto` よりも優れた結果が得られます。有効な値は以下のとおりです。 `Chinese` `English` `German` `Italian` `Portuguese` `Spanish` `Japanese` `Korean` `French` `Russian`
mode	str	いいえ	インタラクションモードです。有効な値は以下のとおりです。 `server_commit`（デフォルト）：サーバーが音声合成のタイミングを自動的に判断し、遅延と品質のバランスを取ります。ほとんどのシナリオでこのモードを推奨します。 `commit`：クライアントが合成を手動でトリガーします。このモードは遅延が最も低くなりますが、文の整合性を自分で管理する必要があります。
format	str	いいえ	モデルからのオーディオ出力のフォーマットです。サポートされるフォーマット： `pcm`（デフォルト） `wav` `mp3` `opus` Qwen-TTS-Realtime（サポートされるモデルを参照）は `pcm` のみをサポートします。
sample_rate	int	いいえ	モデルからのオーディオ出力のサンプルレート（Hz 単位）です。サポートされるサンプルレート： 8000 16000 24000（デフォルト） 48000 Qwen-TTS-Realtime（サポートされるモデルを参照）は 24000 のみをサポートします。
speech_rate	float	いいえ	オーディオの話速です。1.0 が通常の速度です。1.0 未満は遅くなり、1.0 より大きいと速くなります。デフォルト値：1.0 有効範囲：[0.5, 2.0] Qwen-TTS-Realtime（サポートされるモデルを参照）はこのパラメーターをサポートしません。
volume	int	いいえ	オーディオのボリュームです。デフォルト値：50 有効範囲：[0, 100] Qwen-TTS-Realtime（サポートされるモデルを参照）はこのパラメーターをサポートしません。
pitch_rate	float	いいえ	合成オーディオのピッチです。デフォルト値：1.0 有効範囲：[0.5, 2.0] Qwen-TTS-Realtime（サポートされるモデルを参照）はこのパラメーターをサポートしません。
bit_rate	int	いいえ	ビットレートを kbps 単位で指定します。ビットレートが高いほどオーディオ品質が向上し、ファイルサイズも大きくなります。このパラメーターは、オーディオフォーマット（`response_format`）が `opus` に設定されている場合にのみ使用できます。デフォルト値：128 有効範囲：[6, 510] Qwen-TTS-Realtime（サポートされるモデルを参照）はこのパラメーターをサポートしません。
instructions	str	いいえ	命令を設定します。詳細については、「リアルタイム音声合成 - Qwen」をご参照ください。デフォルト値：None。設定されていない場合、このパラメーターはアクティブになりません。長さ制限：長さは 1600 トークンを超えることはできません。サポート言語：中国語および英語のみ。適用範囲：この機能は Qwen3-TTS-Instruct-Flash-Realtime モデルシリーズでのみ利用可能です。
optimize_instructions	bool	いいえ	`instructions` を最適化して、音声合成の自然さと表現力を向上させるかどうかを指定します。デフォルト値：False 動作：True に設定すると、システムは `instructions` を意味的に強化および再書き込みし、音声合成に最適化された内部命令を生成します。適用シナリオ：高品質で詳細な音声表現が求められるシナリオで推奨されます。依存関係：このパラメーターは `instructions` パラメーターが設定されていることを前提としています。`instructions` が空の場合、このパラメーターは効果を持ちません。適用範囲：この機能は Qwen3-TTS-Instruct-Flash-Realtime モデルシリーズでのみ利用可能です。

主要インターフェイス

QwenTtsRealtime クラス

インポート：from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime

メソッドシグネチャー	サーバー応答イベント（コールバック経由で配信）	説明
`def connect(self) -> None`	session.created セッション作成完了 session.updated セッション構成更新完了	サーバーに接続します。
`def update_session(self, voice: str, response_format: AudioFormat = AudioFormat. PCM_24000HZ_MONO_16BIT, mode: str = 'server_commit', language_type : str = "Chinese", **kwargs) -> None`	session.updated セッション構成更新完了	デフォルトのセッション構成を更新します。パラメーターの詳細については、リクエストパラメーターのセクションをご参照ください。接続後、サーバーはデフォルトの入力および出力構成を返します。接続直後にこのメソッドを呼び出して、これらのデフォルト値を更新してください。サーバーは session.update イベントを受信した際にパラメーターを検証します。検証に失敗した場合はエラーを返し、成功した場合はセッション構成を更新します。
`def append_text(self, text: str) -> None`	なし	テキストチャンクをクラウド入力バッファー（送信前のテキストの一時ストレージ）に追加します。サーバーコミットモードでは、サーバーがバッファー内のテキストの送信および合成タイミングを決定します。コミットモードでは、クライアントが commit を呼び出して合成をトリガーする必要があります。
`def clear_appended_text(self, ) -> None`	input_text_buffer.cleared サーバーが受信した平文	クラウドバッファー内のすべてのテキストを削除します。
`def commit(self, ) -> None`	input_text_buffer.committed テキストを送信して音声合成をトリガー response.output_item.added 新しい出力コンテンツが追加されました response.content_part.added アシスタントメッセージに新しいコンテンツが追加されました response.audio.delta モデルによって生成された増分オーディオ response.audio.done オーディオ生成完了 response.content_part.done アシスタントメッセージのオーディオコンテンツのストリーミング完了 response.output_item.done アシスタントメッセージの出力アイテム全体のストリーミング完了 response.done 応答完了	クラウドバッファー内のすべてのテキストを送信し、即座に合成を実行します。バッファーが空の場合、エラーを返します。サーバーコミットモードでは、クライアントがこのイベントを送信する必要はありません。サーバーが自動的にバッファーを送信します。コミットモードでは、クライアントが commit を呼び出して音声合成をトリガーする必要があります。
`def finish(self, ) -> None`	session.finished 応答完了	タスクを終了します。
`def close(self, ) -> None`	なし	接続を閉じます。
`def get_session_id(self) -> str`	なし	現在のタスクのセッション ID を取得します。
`def get_last_response_id(self) -> str`	なし	最新の応答のレスポンス ID を取得します。
`def get_first_audio_delay(self)`	なし	最初のオーディオパケットが到着するまでの遅延時間を取得します。

コールバックインターフェイス (QwenTtsRealtimeCallback)

サーバーはコールバックを通じて応答およびデータを送信します。コールバックメソッドを実装してこれらを処理してください。

インポート：from dashscope.audio.qwen_tts_realtime import QwenTtsRealtimeCallback

メソッド	パラメーター	戻り値	説明
`def on_open(self) -> None`	なし	なし	サーバー接続が確立されたときに呼び出されます。
`def on_event(self, message: str) -> None`	message：サーバー応答イベント。	なし	API 呼び出しの応答、モデルが生成したテキスト、オーディオなどを含みます。「サーバーイベント」をご参照ください。
`def on_close(self, close_status_code, close_msg) -> None`	close_status_code：WebSocket のクローズステータスコード。 close_msg：WebSocket のクローズメッセージ。	なし	サーバーが接続を閉じた後に呼び出されます。