Skip to main content

Python SDK

このトピックでは、DashScope Python SDK を使用して Qwen-TTS-Realtime シリーズのモデルを呼び出す際の、主要なインターフェースとリクエストパラメーターを説明します。

前提条件

DashScope Python SDK のバージョンは 2.0.1 以降である必要があります。

開始方法

import os
import base64
import time
from concurrent.futures import ThreadPoolExecutor

import dashscope

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!'
]

# API キーは、シンガポールリージョンと北京リージョンで異なります。API キーの取得: https://www.alibabacloud.com/help/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio API キーに置き換えてください: api_key="sk-xxx"
client = dashscope.Client(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下はシンガポール (ap-southeast-1) リージョンの設定です。呼び出す際に、"{WorkspaceId}" を実際のワークスペース ID に置き換えてください。設定はリージョンによって異なります。
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

# 受信スレッド:サーバーイベントを反復処理し、音声をファイルに増分書き込みします
def receive_events(session):
    with open('result_24k.pcm', 'wb') as f:
        for event in session.events():
            event_type = event.get('type')
            if event_type == 'session.created':
                print('start session: {}'.format(event['session']['id']))
            elif event_type == 'response.audio.delta':
                f.write(base64.b64decode(event['delta']))
            elif event_type == 'response.done':
                print(f'response {session.last_response_id} done')
            elif event_type == 'session.finished':
                print('session finished')

if __name__  == '__main__':
    print('Initializing ...')

    # リアルタイム音声合成セッションを作成します:with コンテキストに入ると自動的に接続が確立されます
    with client.audio.realtime.connect(
            model='qwen3-tts-flash-realtime',
    ) as session:
        session.update_session(
            output_modalities=['audio'],
            voice='Cherry',
            response_format='pcm',
            sample_rate=24000,
            mode='server_commit'
        )
        with ThreadPoolExecutor(max_workers=1) as pool:
            receiver = pool.submit(receive_events, session)
            for text_chunk in text_to_synthesize:
                print(f'send text: {text_chunk}')
                session.send_event({'type': 'input_text_buffer.append', 'text': text_chunk})
                time.sleep(0.1)
            # サーバーに入力完了を通知します (server_commit モードでは、サーバーが合成タイミングを決定します)
            session.end_session()
            receiver.result()
        print('[Metric] session: {}, first audio delay: {}'.format(
            session.session_id,
            session.last_first_audio_delay,
        ))
詳細については、GitHub にアクセスして、追加のサンプルコードをダウンロードしてください。

リクエストパラメータ

以下のリクエストパラメーターは client.audio.realtime の connect メソッドで設定します。

パラメーター

タイプ

必須

説明

model

str

はい

モデル名 (「サポートされているモデル」をご参照ください)。

ws_url

str

いいえ

セッションエンドポイントです。省略した場合、Client の構築パラメーター workspace/region から自動的に導出されます(中国(北京)地域:wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/realtime、シンガポール地域:wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime)。

以下のリクエストパラメーターはセッションの update_session メソッドで設定します(具名パラメーターは直接渡され、その他のパラメーターは session.update イベントの session オブジェクトに透過されます)。

パラメーター

タイプ

必須

説明

voice

str

はい

音声合成に使用する音声です。詳細については、「Qwen-TTS ボイスリスト」をご参照ください。

language_type

str

いいえ

合成オーディオの言語です。デフォルト値は Auto です。

  • Auto:テキストの言語が不明な場合や、複数の言語が混在している場合に使用します。モデルはテキスト内の異なる言語セグメントに対して自動的に発音をマッチングしますが、完全な精度は保証できません。

  • 特定の言語:単一言語のテキストに使用します。言語を指定することで合成品質が大幅に向上し、通常は Auto よりも優れた結果が得られます。有効な値は以下のとおりです。

    • Chinese

    • English

    • German

    • Italian

    • Portuguese

    • Spanish

    • Japanese

    • Korean

    • French

    • Russian

mode

str

いいえ

インタラクションパターンです。有効な値は以下のとおりです。

  • server_commit (デフォルト):サーバーが自動的に合成タイミングを判断し、レイテンシと品質のバランスを取ります。ほとんどのシナリオでこのパターンを推奨します。

  • commit:クライアントが手動で合成をトリガーします。このパターンは最低のレイテンシを実現しますが、文の整合性を管理する必要があります。

response_format

str

いいえ

モデルからのオーディオ出力フォーマットです。

サポートされるフォーマット:

  • pcm (デフォルト)

  • wav

  • mp3

  • opus

sample_rate

int

いいえ

モデルからのオーディオ出力のサンプルレート (Hz) です。

サポートされるサンプルレート:

  • 8000

  • 16000

  • 24000 (デフォルト)

  • 48000

speech_rate

float

いいえ

オーディオの話速です。1.0 が通常速度です。1.0 未満は低速、1.0 より大きい値は高速になります。

デフォルト値:1.0

有効範囲:[0.5, 2.0]

volume

int

いいえ

オーディオのボリュームです。

有効範囲:[0, 100]

pitch_rate

float

いいえ

合成オーディオのピッチです。

デフォルト値:1.0

有効範囲:[0.5, 2.0]

bit_rate

int

いいえ

ビットレート (kbps) です。ビットレートが高いほどオーディオ品質が向上し、ファイルサイズも大きくなります。このパラメーターは、オーディオフォーマット (response_format) が opus に設定されている場合にのみ使用できます。

デフォルト値:128

有効範囲:[6, 510]

主要なインターフェイス

セッション(RealtimeSession)

リアルタイム音声合成セッションは client.audio.realtime.connect(model=...) で作成されます。with コンテキストに入ると自動的に接続が確立されます(セッションの connect() メソッドを手動で呼び出すこともできます)。
メソッドシグネチャサーバー応答イベント(events() で反復配信)説明
def connect(self) -> "RealtimeSession"
session.created
Session created
session.updated
Session configuration updated
サーバーとの接続を作成します。with コンテキストに入ると自動的に呼び出されます。
def update_session(self,
                   output_modalities: List[str],
                   *,
                   voice: str = None,
                   **kwargs) -> None
session.updated
Session configuration updated
デフォルトのセッション構成を更新します。パラメーターの詳細については、「Request parameters」をご参照ください。接続後、サーバーはデフォルトの入力構成と出力構成を返します。接続直後にこのメソッドを呼び出し、これらのデフォルト設定を更新します。サーバーは session.update イベントを受信した時点でパラメーターを検証します。検証に失敗した場合はエラーを返し、成功した場合はセッション構成を更新します。
def send_event(self,
               event: Dict[str, Any]) -> None
None生のイベントを送信します。テキスト入力は input_text_buffer 系列のイベントで行います:テキストチャンクをクラウド入力テキストバッファー({"type": "input_text_buffer.append", "text": ...})に追加します。バッファーは、書き込んで後でコミットできる一時ストレージです。
  • server_commit モードでは、サーバーがテキストバッファーをいつコミットして合成するかを決定します。
  • commit モードでは、クライアントが input_text_buffer.commit イベントを能動的に送信して音声合成をトリガーする必要があります。
def send_event(self,
               event: Dict[str, Any]) -> None
input_text_buffer.cleared
Clear text received by the server
{"type": "input_text_buffer.clear"} イベントを送信し、現在のクラウドバッファー内のテキストを削除します。
def send_event(self,
               event: Dict[str, Any]) -> None
input_text_buffer.committed
Submit text and trigger speech synthesis
response.output_item.added
New output content added
response.content_part.added
New content added to assistant message
response.audio.delta
Incremental audio generated by the model
response.audio.done
Audio generation completed
response.content_part.done
Streaming of audio content for assistant message completed
response.output_item.done
Streaming of entire output item for assistant message completed
response.done
Synthesis response completed
クラウドバッファー内のテキストをすべてコミットし、直ちに音声合成します。バッファーが空の場合はエラーを返します。
  • server_commit モードでは、クライアントがこのイベントを送信する必要はありません。サーバーがバッファーを自動でコミットします。
  • commit モードでは、クライアントが commit を呼び出して音声合成をトリガーする必要があります。
def end_session(self) -> None
session.finished
Session completed
session.finish イベントを送信してタスクを終了します。その後も session.finished イベントまで events() を消費し続けてください。
def close(self, ) -> None
None接続を閉じます。with コンテキストの退出時に自動的に呼び出されます。
session.session_id
None現在のタスクの session_id を取得します。
session.last_response_id
None直近の response の response_id を取得します。
session.last_first_audio_delay
None最初の音声パケットの遅延を取得します。

イベント反復(events())

サーバーは、イベントを通じてサーバー応答イベントとデータをクライアントに返します。受信スレッドでセッションの events() を反復処理してサーバーイベントを処理します。session.finished イベントの後に反復が終了します。error イベントは DashScopeError 例外としてスローされるため、try/except で捕捉できます。
メソッドパラメーター戻り値説明
def events(self) -> Iterator[Dict]
event:サーバー応答イベント(dict)。反復子API 呼び出しへの応答とモデルが生成したテキスト、オーディオが含まれます。session.finished イベントの後に反復が終了します。詳細については、「Server events」をご参照ください。
def recv_event(self) -> Optional[Dict]
event:サーバー応答イベント(dict)。イベントまたは Noneサーバーイベントを 1 件読み取ります。正常に閉じられた後は None を返します。