すべてのプロダクト
Search
ドキュメントセンター

Alibaba Cloud Model Studio:CosyVoice speech synthesis Python SDK

最終更新日:Jan 17, 2026

このトピックでは、音声合成のための CosyVoice Python SDK のパラメーターとインターフェイスの詳細について説明します。

重要

中国 (北京) リージョンのモデルを使用するには、中国 (北京) リージョンの API キーページに移動してください。

ユーザーガイド:モデルの詳細とモデル選択のガイダンスについては、「リアルタイム音声合成 - CosyVoice」をご参照ください。

前提条件

  • Model Studio を有効化し、API キーを作成済みであること。セキュリティリスクを防ぐため、API キーをコードにハードコーディングするのではなく、API キーを環境変数としてエクスポートしてください。

    説明

    サードパーティのアプリケーションやユーザーに一時的なアクセス権限を付与する場合、または機密データへのアクセスや削除などのリスクの高い操作を厳密に制御したい場合は、一時的な認証トークンの使用を推奨します。

    長期的な API キーと比較して、一時的な認証トークンは有効期間が短い (60 秒) ため、より安全です。これらは一時的な呼び出しシナリオに適しており、API キー漏洩のリスクを効果的に低減できます。

    一時的なトークンを使用するには、コード内の認証に使用する API キーを一時的な認証トークンに置き換えてください。

  • DashScope SDK の最新バージョンをインストールする

モデルと料金

モデル

料金

無料クォータ (注)

cosyvoice-v3-plus

0.286706 ドル/10,000 文字

無料クォータなし

cosyvoice-v3-flash

0.14335 ドル/10,000 文字

cosyvoice-v2

0.286706 ドル/10,000 文字

テキストとフォーマットの制限

テキスト長の制限

文字数カウントルール

  • 簡体字または繁体字中国語、日本の漢字、韓国の漢字を含む中国語の文字は、2 文字としてカウントされます。句読点、アルファベット、数字、日本語のかな、韓国のハングルなど、その他のすべての文字は 1 文字としてカウントされます。

  • SSML タグはテキスト長の計算に含まれません。

  • 例:

    • "你好" → 2(你) + 2(好) = 4 文字

    • "中A文123" → 2(中) + 1(A) + 2(文) + 1(1) + 1(2) + 1(3) = 8 文字

    • "中文。" → 2(中) + 2(文) + 1(。) = 5 文字

    • "中 文。" → 2(中) + 1(スペース) + 2(文) + 1(。) = 6 文字

    • "<speak>你好</speak>" → 2(你) + 2(好) = 4 文字

エンコーディング形式

UTF-8 エンコーディングを使用してください。

数式のサポート

数式解析機能は、現在 cosyvoice-v2cosyvoice-v3-flash、および cosyvoice-v3-plus モデルでのみ利用可能です。この機能は、基本的な算術、代数、幾何学など、小中学校で一般的に使用される数式をサポートします。

LaTeX 数式読み上げ」をご参照ください。

SSML サポート

音声合成マークアップ言語 (SSML) 機能は、現在 cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 モデルのクローン音声、および音声リストでサポートされていると示されているシステム音声でのみ利用可能です。以下の条件を満たす必要があります:

はじめに

SpeechSynthesizer クラスは音声合成の主要なクラスであり、以下の呼び出しメソッドをサポートしています:

  • 非ストリーミング呼び出し:完全なテキストを一度に送信し、完全な音声を直接返すブロッキング呼び出し。このメソッドは、短いテキストの合成シナリオに適しています。

  • 単方向ストリーミング呼び出し:完全なテキストを一度に送信し、コールバック関数を使用して音声データを受信する非ブロッキング呼び出し。音声データはチャンクで配信される場合があります。このメソッドは、低遅延が要求される短いテキストの合成シナリオに適しています。

  • 双方向ストリーミング呼び出し:テキストを断片的に送信し、コールバック関数を使用して合成された音声ストリームをリアルタイムで増分的に受信する非ブロッキング呼び出し。このメソッドは、低遅延が要求される長いテキストの合成シナリオに適しています。

非ストリーミング呼び出し

このメソッドは、コールバック関数を使用せずに単一の音声合成タスクを送信します。合成は中間結果をストリーミングせず、代わりに完全な結果が一度に返されます。

image

SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターをアタッチし、call メソッドを呼び出してテキストを合成し、バイナリ音声データを取得できます。

送信するテキストは 2,000 文字を超えることはできません。詳細については、SpeechSynthesizer クラスcall メソッドをご参照ください。

重要

call メソッドを呼び出すたびに、新しい SpeechSynthesizer インスタンスを作成する必要があります。

完全なサンプルを表示するにはクリック

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *

# API キーを環境変数として設定していない場合は、「your-api-key」を実際の API キーに置き換えてください。
# dashscope.api_key = "your-api-key"

# モデル
model = "cosyvoice-v3-flash"
# 音声
voice = "longanyang"

# SpeechSynthesizer をインスタンス化し、コンストラクターでモデルや音声などのリクエストパラメーターを渡します。
synthesizer = SpeechSynthesizer(model=model, voice=voice)
# 合成するテキストを送信し、バイナリ音声データを取得します。
audio = synthesizer.call("今日の天気はどうですか?")
# 初めてテキストを送信する際には、WebSocket 接続を確立する必要があります。そのため、初回パケット遅延には接続確立にかかる時間が含まれます。
print('[メトリック] リクエスト ID: {}, 初回パケット遅延: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

# 音声をローカルファイルに保存します。
with open('output.mp3', 'wb') as f:
    f.write(audio)

単方向ストリーミング呼び出し

このメソッドは、単一の音声合成タスクを送信します。中間結果はコールバックを介してストリーミングされ、最終的な合成結果は ResultCallback コールバック関数を介してストリーミングされます。

image

SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターResultCallback インターフェイスをアタッチし、call メソッドを呼び出して合成を実行します。その後、ResultCallback インターフェイスon_data メソッドを介してリアルタイムの合成結果を取得できます。

送信するテキストの長さは 2,000 文字を超えることはできません。詳細については、SpeechSynthesizer クラスcall メソッドをご参照ください。

重要

call メソッドを呼び出すたびに、新しい SpeechSynthesizer インスタンスを作成する必要があります。

完全なサンプルを表示するにはクリック

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *

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 キーを環境変数として設定していない場合は、「your-api-key」を実際の API キーに置き換えてください。
# dashscope.api_key = "your-api-key"

# モデル
model = "cosyvoice-v3-flash"
# 音声
voice = "longanyang"


# コールバックインターフェイスを定義します。
class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        self.file = open("output.mp3", "wb")
        print("接続が確立されました: " + get_timestamp())

    def on_complete(self):
        print("音声合成が完了しました。すべての結果が受信されました: " + get_timestamp())
        # タスクが完了した後 (on_complete コールバックがトリガーされた後) にのみ、get_first_package_delay を呼び出して遅延を取得します。
        # 初めてテキストを送信する際には、WebSocket 接続を確立する必要があります。そのため、初回パケット遅延には接続確立にかかる時間が含まれます。
        print('[メトリック] リクエスト ID: {}, 初回パケット遅延: {} ms'.format(
            synthesizer.get_last_request_id(),
            synthesizer.get_first_package_delay()))

    def on_error(self, message: str):
        print(f"音声合成中にエラーが発生しました: {message}")

    def on_close(self):
        print("接続が閉じられました: " + get_timestamp())
        self.file.close()

    def on_event(self, message):
        pass

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " バイナリ音声データの長さ: " + str(len(data)))
        self.file.write(data)


callback = Callback()

# SpeechSynthesizer をインスタンス化し、コンストラクターでモデルや音声などのリクエストパラメーターを渡します。
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    callback=callback,
)

# 合成するテキストを送信し、コールバックの on_data メソッドでバイナリ音声データをリアルタイムで受信します。
synthesizer.call("今日の天気はどうですか?")

双方向ストリーミング呼び出し

このメソッドでは、1 回の音声合成タスク内でテキストを複数回に分けて送信し、コールバックを介して合成結果をリアルタイムで受信できます。

説明
  • 入力をストリーミングするには、streaming_call メソッドを複数回呼び出して、テキストの断片を順番に送信します。サーバーはテキストの断片を受信すると、自動的に文に分割します:

    • 完全な文はすぐに合成されます。

    • 不完全な文はバッファリングされ、完全になってから合成されます。

    streaming_complete メソッドを呼び出すと、サーバーは受信したが未処理のすべてのテキスト断片 (不完全な文を含む) を合成します。

  • テキスト断片を送信する間隔は 23 秒を超えることはできません。超えた場合、「request timeout after 23 seconds」例外が発生します。

    送信するテキストがこれ以上ない場合は、streaming_complete メソッドを呼び出してタスクを終了する必要があります。

    サーバーは 23 秒のタイムアウトを強制します。クライアントはこの構成を変更できません。
image
  1. SpeechSynthesizer クラスをインスタンス化できます。

    SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターResultCallback コールバックインターフェイスをアタッチします。

  2. ストリーミングデータ

    SpeechSynthesizer クラスstreaming_call メソッドを複数回呼び出してデータをストリーミングします。これにより、合成するテキストがセグメント単位でサーバー側に送信されます。

    テキストを送信している間、サーバーはResultCallback インターフェイスon_data メソッドを使用して、合成された結果をリアルタイムでクライアントに返します。

    streaming_call メソッドの各呼び出しで送信されるテキストセグメント (text パラメーター) の長さは 2,000 文字を超えることはできません。送信するすべてのテキストの累積長は 200,000 文字を超えることはできません。

  3. 処理完了

    SpeechSynthesizer クラスstreaming_complete メソッドを呼び出してプロセスを終了し、音声合成タスクを完了させます。

    このメソッドは、ResultCallback インターフェイスon_complete または on_error メソッドがトリガーされるまで、現在のスレッドをブロックします。

    このメソッドを呼び出す必要があります。そうしないと、テキストの末尾が正常に合成されない可能性があります。

完全なサンプルを表示するにはクリック

# 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 time
import pyaudio
import dashscope
from dashscope.api_entities.dashscope_response import SpeechSynthesisResponse
from dashscope.audio.tts_v2 import *

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 キーを環境変数として設定していない場合は、「your-api-key」を実際の API キーに置き換えてください。
# dashscope.api_key = "your-api-key"

# モデル
model = "cosyvoice-v3-flash"
# 音声
voice = "longanyang"


# コールバックインターフェイスを定義します。
class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        print("接続が確立されました: " + get_timestamp())
        self._player = pyaudio.PyAudio()
        self._stream = self._player.open(
            format=pyaudio.paInt16, channels=1, rate=22050, output=True
        )

    def on_complete(self):
        print("音声合成が完了しました。すべての結果が受信されました: " + get_timestamp())

    def on_error(self, message: str):
        print(f"音声合成中にエラーが発生しました: {message}")

    def on_close(self):
        print("接続が閉じられました: " + get_timestamp())
        # プレーヤーを停止します。
        self._stream.stop_stream()
        self._stream.close()
        self._player.terminate()

    def on_event(self, message):
        pass

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " バイナリ音声データの長さ: " + str(len(data)))
        self._stream.write(data)


callback = Callback()

test_text = [
    "ストリーミングテキスト読み上げ SDK は、",
    "入力されたテキストを",
    "バイナリの音声データに変換できます。",
    "非ストリーミング音声合成と比較して、",
    "ストリーミング合成の利点は、その低遅延にあります。",
    "ユーザーはテキストを入力しながら、",
    "ほぼ同期した音声出力を聞くことができ、",
    "これによりインタラクティブな体験が大幅に向上し、",
    "ユーザーの待機時間が短縮されます。",
    "これは、大規模言語モデル (LLM) を呼び出して、",
    "ストリーミングテキスト入力で",
    "音声合成を実行するシナリオに適しています。",
]

# SpeechSynthesizer をインスタンス化し、コンストラクターでモデルや音声などのリクエストパラメーターを渡します。
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    format=AudioFormat.PCM_22050HZ_MONO_16BIT,  
    callback=callback,
)


# 合成するテキストをストリーミングします。コールバックインターフェイスの on_data メソッドでバイナリ音声データをリアルタイムで受信します。
for text in test_text:
    synthesizer.streaming_call(text)
    time.sleep(0.1)
# ストリーミング音声合成を終了します。
synthesizer.streaming_complete()

# 初めてテキストを送信する際には、WebSocket 接続を確立する必要があります。そのため、初回パケット遅延には接続確立にかかる時間が含まれます。
print('[メトリック] リクエスト ID: {}, 初回パケット遅延: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

リクエストパラメーター

SpeechSynthesizer クラスのコンストラクターでリクエストパラメーターを設定できます。

パラメーター

タイプ

必須

説明

model

str

はい

音声合成モデル

異なるモデルには対応する音声が必要です:

  • cosyvoice-v3-flash/cosyvoice-v3-plus: longanyang などの音声を使用します。

  • cosyvoice-v2: longxiaochun_v2 などの音声を使用します。

  • 完全なリストについては、「音声リスト」をご参照ください。

voice

str

はい

音声合成に使用する音声。

システム音声とクローン音声がサポートされています:

  • システム音声:「音声リスト」をご参照ください。

  • クローン音声音声クローン機能を使用して音声をカスタマイズします。クローン音声を使用する場合、音声クローンと音声合成の両方で同じアカウントが使用されていることを確認してください。詳細な手順については、「CosyVoice 音声クローン API」をご参照ください。

    クローン音声を使用する場合、リクエストの model パラメーターの値は、音声を作成するために使用されたモデルバージョン (target_model パラメーター) と完全に同じでなければなりません。

format

enum

いいえ

音声のコーディング形式とサンプルレートを指定します。

format が指定されていない場合、合成された音声はサンプルレート 22.05 kHz の MP3 形式になります。

説明

デフォルトのサンプルレートは、現在の音声に最適なレートです。デフォルトでは、出力はこのサンプルレートを使用します。ダウンサンプリングとアップサンプリングもサポートされています。

以下の音声コーディング形式とサンプルレートを指定できます:

  • すべてのモデルでサポートされている音声コーディング形式とサンプルレート:

    • AudioFormat.WAV_8000HZ_MONO_16BIT:音声フォーマットは WAV、サンプルレートは 8 kHz です。

    • AudioFormat.WAV_16000HZ_MONO_16BIT:音声フォーマットは WAV、サンプルレートは 16 kHz です。

    • AudioFormat.WAV_22050HZ_MONO_16BIT:音声フォーマットは WAV、サンプルレートは 22.05 kHz です。

    • AudioFormat.WAV_24000HZ_MONO_16BIT:音声フォーマットは WAV、サンプルレートは 24 kHz です。

    • AudioFormat.WAV_44100HZ_MONO_16BIT:音声フォーマットは WAV、サンプルレートは 44.1 kHz です。

    • AudioFormat.WAV_48000HZ_MONO_16BIT:音声フォーマットは WAV、サンプルレートは 48 kHz です。

    • AudioFormat.MP3_8000HZ_MONO_128KBPS:音声フォーマットは MP3、サンプルレートは 8 kHz です。

    • AudioFormat.MP3_16000HZ_MONO_128KBPS:音声フォーマットは MP3、サンプルレートは 16 kHz です。

    • AudioFormat.MP3_22050HZ_MONO_256KBPS:音声フォーマットは MP3、サンプルレートは 22.05 kHz です。

    • AudioFormat.MP3_24000HZ_MONO_256KBPS:音声フォーマットは MP3、サンプルレートは 24 kHz です。

    • AudioFormat.MP3_44100HZ_MONO_256KBPS:音声フォーマットは MP3、サンプルレートは 44.1 kHz です。

    • AudioFormat.MP3_48000HZ_MONO_256KBPS:音声フォーマットは MP3、サンプルレートは 48 kHz です。

    • AudioFormat.PCM_8000HZ_MONO_16BIT:音声フォーマットは PCM、サンプルレートは 8 kHz です。

    • AudioFormat.PCM_16000HZ_MONO_16BIT:音声フォーマットは PCM、サンプルレートは 16 kHz です。

    • AudioFormat.PCM_22050HZ_MONO_16BIT:音声フォーマットは PCM、サンプルレートは 22.05 kHz です。

    • AudioFormat.PCM_24000HZ_MONO_16BIT:音声フォーマットは PCM、サンプルレートは 24 kHz です。

    • AudioFormat.PCM_44100HZ_MONO_16BIT:音声フォーマットは PCM、サンプルレートは 44.1 kHz です。

    • AudioFormat.PCM_48000HZ_MONO_16BIT:音声フォーマットは PCM、サンプルレートは 48 kHz です。

  • 音声フォーマットが Opus の場合、bit_rate パラメーターを使用してビットレートを調整します。この機能は DashScope SDK バージョン 1.24.0 以降でのみ利用可能です。

    • AudioFormat.OGG_OPUS_8KHZ_MONO_32KBPS:音声フォーマットは Opus、サンプルレートは 8 kHz、ビットレートは 32 kbps です。

    • AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS:音声フォーマットは Opus、サンプルレートは 16 kHz、ビットレートは 16 kbps です。

    • AudioFormat.OGG_OPUS_16KHZ_MONO_32KBPS:音声フォーマットは Opus、サンプルレートは 16 kHz、ビットレートは 32 kbps です。

    • AudioFormat.OGG_OPUS_16KHZ_MONO_64KBPS:音声フォーマットは Opus、サンプルレートは 16 kHz、ビットレートは 64 kbps です。

    • AudioFormat.OGG_OPUS_24KHZ_MONO_16KBPS:音声フォーマットは Opus、サンプルレートは 24 kHz、ビットレートは 16 kbps です。

    • AudioFormat.OGG_OPUS_24KHZ_MONO_32KBPS:音声フォーマットは Opus、サンプルレートは 24 kHz、ビットレートは 32 kbps です。

    • AudioFormat.OGG_OPUS_24KHZ_MONO_64KBPS:音声フォーマットは Opus、サンプルレートは 24 kHz、ビットレートは 64 kbps です。

    • AudioFormat.OGG_OPUS_48KHZ_MONO_16KBPS:音声フォーマットは Opus、サンプルレートは 48 kHz、ビットレートは 16 kbps です。

    • AudioFormat.OGG_OPUS_48KHZ_MONO_32KBPS:音声フォーマットは Opus、サンプルレートは 48 kHz、ビットレートは 32 kbps です。

    • AudioFormat.OGG_OPUS_48KHZ_MONO_64KBPS:音声フォーマットは Opus、サンプルレートは 48 kHz、ビットレートは 64 kbps です。

volume

int

いいえ

ボリューム。

デフォルト値:50。

有効値:[0, 100]。値 50 は標準のボリュームです。ボリュームはこの値と線形の関係にあります。0 はミュート、100 は最大ボリュームです。

重要

このフィールドは DashScope SDK のバージョンによって異なります:

  • SDK バージョン 1.20.10 以降:volume

  • SDK バージョン 1.20.10 未満:volumn

speech_rate

float

いいえ

話速。

デフォルト値:1.0。

有効値:[0.5, 2.0]。値 1.0 は標準の速度です。1.0 未満の値は話速を遅くし、1.0 より大きい値は話速を速くします。

pitch_rate

float

いいえ

ピッチ。この値はピッチ調整の乗数です。この値と知覚されるピッチとの関係は、厳密に線形または対数ではありません。最適な値を見つけるために、さまざまな値をテストしてください。

デフォルト値:1.0。

有効値:[0.5, 2.0]。値 1.0 は音声の自然なピッチです。1.0 より大きい値はピッチを高くし、1.0 未満の値はピッチを低くします。

bit_rate

int

いいえ

音声ビットレート (kbps)。音声フォーマットが Opus の場合、bit_rate パラメーターを使用してビットレートを調整できます。

デフォルト値:32。

有効値:[6, 510]。

説明

bit_rateadditional_params パラメーターを使用して設定する必要があります:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longanyang",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"bit_rate": 32})

word_timestamp_enabled

bool

いいえ

単語レベルのタイムスタンプを有効にするかどうかを指定します。

デフォルト値:False。

  • True

  • False

この機能は、cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 モデルのクローン音声、および音声リストでサポートされているとマークされたシステム音声にのみ適用されます。

タイムスタンプの結果は、コールバックインターフェイスを介してのみ取得できます。
説明

word_timestamp_enabledadditional_params パラメーターを使用して設定する必要があります:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longyingjing_v3",
                                callback=callback, # タイムスタンプの結果はコールバックインターフェイスを介してのみ取得できます。
                                additional_params={'word_timestamp_enabled': True})

完全なサンプルコードを表示するにはクリック

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import json
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 キーを環境変数として設定していない場合は、「your-api-key」を実際の API キーに置き換えてください。
# dashscope.api_key = "your-api-key"

# cosyvoice-v2 モデルのみがサポートされています。
model = "cosyvoice-v3-flash"
# 音声
voice = "longyingjing_v3"


# コールバックインターフェイスを定義します。
class Callback(ResultCallback):
    _player = None
    _stream = None

    def on_open(self):
        self.file = open("output.mp3", "wb")
        print("接続が確立されました: " + get_timestamp())

    def on_complete(self):
        print("音声合成が完了しました。すべての結果が受信されました: " + get_timestamp())

    def on_error(self, message: str):
        print(f"音声合成中にエラーが発生しました: {message}")

    def on_close(self):
        print("接続が閉じられました: " + get_timestamp())
        self.file.close()

    def on_event(self, message):
        json_data = json.loads(message)
        if json_data['payload'] and json_data['payload']['output'] and json_data['payload']['output']['sentence']:
            sentence = json_data['payload']['output']['sentence']
            print(f'sentence: {sentence}')
            # 文番号を取得します。
            # index = sentence['index']
            words = sentence['words']
            if words:
                for word in words:
                    print(f'word: {word}')
                    # サンプル値: word: {'text': 'What', 'begin_index': 0, 'end_index': 1, 'begin_time': 80, 'end_time': 200}

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " バイナリ音声データの長さ: " + str(len(data)))
        self.file.write(data)


callback = Callback()

# SpeechSynthesizer をインスタンス化し、コンストラクターでモデルや音声などのリクエストパラメーターを渡します。
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    callback=callback,
    additional_params={'word_timestamp_enabled': True}
)

# 合成するテキストを送信し、コールバックインターフェイスの on_data メソッドでバイナリ音声データをリアルタイムで受信します。
synthesizer.call("今日の天気はどうですか?")
# 初めてテキストを送信する際には、WebSocket 接続を確立する必要があります。そのため、初回パケット遅延には接続確立にかかる時間が含まれます。
print('[メトリック] リクエスト ID: {}, 初回パケット遅延: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

seed

int

いいえ

生成中に使用される乱数シードで、合成効果を変化させます。モデルバージョン、テキスト、音声、その他のパラメーターが同じ場合、同じシードを使用すると同じ合成結果が再現されます。

デフォルト値:0。

有効値:[0, 65535]。

language_hints

list[str]

いいえ

音声合成のターゲット言語を指定して、合成効果を向上させます。

数字、略語、記号の発音や、中国語以外の言語の合成効果が期待通りでない場合にこのパラメーターを使用します。

有効な値:

  • zh:中国語

  • en:英語

  • fr:フランス語

  • de:ドイツ語

  • ja:日本語

  • ko:韓国語

  • ru:ロシア語

:このパラメーターは配列ですが、現在のバージョンでは最初の要素のみが処理されます。したがって、1 つの値のみを渡す必要があります。

重要

このパラメーターは、音声合成のターゲット言語を指定します。この設定は、音声クローンに使用されるサンプル音声の言語とは無関係です。音声クローンタスクのソース言語を設定するには、「CosyVoice 音声クローン API」をご参照ください。

instruction

str

いいえ

命令の設定:この機能は、cosyvoice-v3-flash および cosyvoice-v3-plus モデルのクローン音声、および音声リストでサポートされているとマークされたシステム音声でのみ利用可能です。

デフォルト値はありません。このパラメーターが設定されていない場合、効果はありません。

音声合成には以下の効果があります:

  1. 方言を指定する (クローン音声のみ)

    • フォーマット:「请用<方言>表达。」(注:末尾のピリオド (。) を省略しないでください。<方言> を特定の方言、例えば 广东话 に置き換えてください。)

    • 例:「请用广东话表达。

    • サポートされている方言:广东话 (広東語)、东北话 (東北語)、甘肃话 (甘粛語)、贵州话 (貴州語)、河南话 (河南語)、湖北话 (湖北語)、江西话 (江西語)、闽南话 (閩南語)、宁夏话 (寧夏語)、山西话 (山西語)、陕西话 (陝西語)、山东话 (山東語)、上海话 (上海語)、四川话 (四川語)、天津话 (天津語)、云南话 (雲南語)。

  2. 感情、シナリオ、役割、または ID を指定します。一部のシステム音声のみがこの機能をサポートしており、音声によって異なります。「音声リスト」をご参照ください。

enable_aigc_tag

bool

いいえ

生成された音声に非表示の AIGC 識別子を追加するかどうかを指定します。True に設定すると、サポートされているフォーマット (WAV、MP3、Opus) の音声に非表示の識別子が埋め込まれます。

デフォルト値:False。

この機能は、cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 モデルでのみサポートされています。

説明

enable_aigc_tagadditional_params パラメーターを使用して設定する必要があります:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longanyang",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"enable_aigc_tag": True})

aigc_propagator

str

いいえ

非表示の AIGC 識別子の ContentPropagator フィールドを設定して、コンテンツの伝播者を識別します。このパラメーターは、enable_aigc_tagTrue の場合にのみ有効です。

デフォルト値:Alibaba Cloud UID。

この機能は、cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 モデルでのみサポートされています。

説明

aigc_propagatoradditional_params パラメーターを使用して設定する必要があります:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longanyang",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"enable_aigc_tag": True, "aigc_propagator": "xxxx"})

aigc_propagate_id

str

いいえ

非表示の AIGC 識別子の PropagateID フィールドを設定して、特定の伝播操作を一意に識別します。このパラメーターは、enable_aigc_tagTrue の場合にのみ有効です。

デフォルト値:現在の音声合成リクエストのリクエスト ID。

この機能は、cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 モデルでのみサポートされています。

説明

aigc_propagate_idadditional_params パラメーターを使用して設定する必要があります:

synthesizer = SpeechSynthesizer(model="cosyvoice-v3-flash",
                                voice="longanyang",
                                format=AudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS,
                                additional_params={"enable_aigc_tag": True, "aigc_propagate_id": "xxxx"})

callback

ResultCallback

いいえ

ResultCallback インターフェイス

主要なインターフェイス

SpeechSynthesizer クラス

SpeechSynthesizer クラスは、音声合成のメインインターフェイスです。このクラスは from dashscope.audio.tts_v2 import * を使用してインポートできます。

メソッド

パラメーター

戻り値

説明

def call(self, text: str, timeout_millis=None)
  • text:合成するテキスト。

  • timeout_millis:ブロッキングスレッドのタイムアウト (ミリ秒)。設定しないか 0 に設定した場合、このパラメーターは効果がありません。

ResultCallback が指定されていない場合はバイナリ音声データを返します。それ以外の場合は None を返します。

テキストのセグメント全体を音声に変換します。テキストはプレーンテキストまたは SSML を含むことができます。

SpeechSynthesizer インスタンスを作成する際、2 つのシナリオが考えられます:

  • ResultCallback を指定しない場合、call メソッドは音声合成が完了するまで現在のスレッドをブロックし、バイナリ音声データを返します。詳細については、「非ストリーミング呼び出し」をご参照ください。

  • ResultCallback を指定した場合、call メソッドはすぐに None を返します。音声合成の結果は、ResultCallback インターフェイスon_data メソッドを介して返されます。詳細については、「単方向ストリーミング呼び出し」をご参照ください。

重要

call メソッドを呼び出すたびに、新しい SpeechSynthesizer インスタンスを作成する必要があります。

def streaming_call(self, text: str)

text:合成するテキストセグメント。

None

合成するテキストをストリーミングします。SSML を含むテキストはサポートされていません。

このインターフェイスを複数回呼び出して、合成するテキストをセグメント単位でサーバーに送信できます。合成結果は、ResultCallback インターフェイスon_data メソッドを介して取得されます。

詳細については、「双方向ストリーミング呼び出し」をご参照ください。

def streaming_complete(self, complete_timeout_millis=600000)

complete_timeout_millis:待機時間 (ミリ秒)。

None

ストリーミング音声合成を終了します。

このメソッドは、タスクが完了するまで、complete_timeout_millis で指定された時間、現在のスレッドをブロックします。completeTimeoutMillis が 0 に設定されている場合、スレッドは無期限に待機します。

デフォルトでは、待機時間が 10 分を超えると待機を停止します。

詳細については、「双方向ストリーミング呼び出し」をご参照ください。

重要

双方向ストリーミング呼び出しを行う際は、このメソッドを呼び出してください。そうしないと、合成された音声が不完全になる可能性があります。

def get_last_request_id(self)

None

最後のタスクのリクエスト ID。

最後のタスクのリクエスト ID を取得します。

def get_first_package_delay(self)

None

初回パケット遅延

初回パケット遅延を取得します。遅延は通常約 500 ms です。

初回パケット遅延は、テキストを送信してから最初の音声パケットを受信するまでの時間 (ミリ秒) です。タスクが完了した後に遅延を確認してください。

初めてテキストを送信する際には、WebSocket 接続を確立する必要があります。そのため、初回パケット遅延には接続確立にかかる時間が含まれます。

def get_response(self)

None

最後のメッセージ

最後のメッセージを JSON 形式で取得します。これを使用して、タスク失敗のエラーを取得できます。

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

単方向ストリーミング呼び出しまたは双方向ストリーミング呼び出しの場合、サーバーは主要なプロセス情報とデータをコールバックを介してクライアントに返します。返された情報とデータを処理するために、コールバックメソッドを実装する必要があります。

from dashscope.audio.tts_v2 import * を使用してインポートできます。

サンプルを表示するにはクリック

class Callback(ResultCallback):
    def on_open(self) -> None:
        print('接続に成功しました')
    
    def on_data(self, data: bytes) -> None:
        # 合成されたバイナリ音声結果を受信するロジックを実装します。

    def on_complete(self) -> None:
        print('合成が完了しました')

    def on_error(self, message) -> None:
        print('例外が発生しました: ', message)

    def on_close(self) -> None:
        print('接続が閉じられました')


callback = Callback()

メソッド

パラメーター

戻り値

説明

def on_open(self) -> None

None

None

サーバーとの接続が確立された直後に呼び出されます。

def on_event( self, message: str) -> None

message:サーバーから返された情報。

None

サービスが応答を送信したときに呼び出されます。message は JSON 文字列です。文字列を解析して、タスク ID (task_id パラメーター) やリクエストの課金対象文字数 (characters パラメーター) などの情報を取得します。

def on_complete(self) -> None

None

None

すべての合成データが返され、音声合成が完了した後に呼び出されます。

def on_error(self, message) -> None

message:エラーメッセージ。

None

例外が発生したときに呼び出されます。

def on_data(self, data: bytes) -> None

data:サーバーから返されたバイナリ音声データ。

None

サーバーが合成された音声を返したときに呼び出されます。

バイナリ音声データを結合して完全な音声ファイルを作成して再生するか、ストリーミング再生をサポートするプレーヤーでリアルタイムに再生します。

重要
  • ストリーミング音声合成では、MP3 や Opus などの圧縮形式の場合、ストリーミングプレーヤーを使用して音声セグメントを再生します。デコード失敗を避けるため、フレームごとに再生しないでください。

    ストリーミング再生をサポートするプレーヤーには、ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (JavaScript) などがあります。
  • 音声データを結合して完全な音声ファイルを作成する場合、データを同じファイルに追加します。

  • ストリーミング音声合成における WAV および MP3 音声フォーマットでは、最初のフレームにのみヘッダー情報が含まれます。後続のフレームには音声データのみが含まれます。

def on_close(self) -> None

None

None

サービスが接続を閉じた後に呼び出されます。

応答

サーバーはバイナリ音声データを返します:

エラーコード

トラブルシューティング情報については、「エラーメッセージ」をご参照ください。

その他の例

その他の例については、GitHub をご参照ください。

よくある質問

機能、課金、レート制限

Q:不正確な発音を修正するにはどうすればよいですか?

SSML を使用して、音声合成の出力をカスタマイズできます。

Q:音声合成はテキストの文字数に基づいて課金されます。各合成のテキスト長を確認または取得するにはどうすればよいですか?

これはロギングが有効になっているかどうかによります:

  1. ロギングは無効になっています。

    • 非ストリーミング呼び出しの場合、文字数カウントルールに従って文字数を計算できます。

    • または、ResultCallback コールバックインターフェイスon_event メソッドの message パラメーターから情報を取得できます。message は JSON 文字列であり、これを解析して現在のリクエストの課金対象文字数を characters パラメーターから取得します。受信した最後の message を使用してください。

  2. ロギングが有効になっています。

    ロギングが有効な場合、コンソールは characters パラメーターを含むログを出力します。このパラメーターは、リクエストの課金対象文字数を示します。リクエストの最後のログエントリの値を使用してください。

    2025-08-27 11:02:09,429 - dashscope - speech_synthesizer.py - on_message - 454 - DEBUG - <<<recv {"header":{"task_id":"62ebb7d6cb0a4080868f0edb######","event":"result-generated","attributes":{}},"payload":{"output":{"sentence":{"words":[]}},"usage":{"characters":15}}}

ロギングを有効にする方法を表示するにはクリック

コマンドラインで環境変数を設定することでロギングを有効にできます:

  • Windows: $env:DASHSCOPE_LOGGING_LEVEL="debug"

  • Linux/macOS: export DASHSCOPE_LOGGING_LEVEL=debug

トラブルシューティング

コードエラーが発生した場合は、「エラーコード」を参照して問題をトラブルシューティングしてください。

Q:リクエスト ID を取得するにはどうすればよいですか?

以下の 2 つの方法のいずれかで取得できます:

Q:SSML 機能が失敗するのはなぜですか?

以下を確認してください:

  1. 範囲が正しいことを確認してください。

  2. 最新バージョンの DashScope SDK をインストールしていることを確認してください。

  3. 正しいインターフェイスを使用していることを確認してください。SSML は SpeechSynthesizer クラスcall メソッドでのみサポートされています。

  4. 合成するテキストがプレーンテキストであり、必要なフォーマットを満たしていることを確認してください。詳細については、「SSML の概要」をご参照ください。

Q:音声が再生できないのはなぜですか?

以下のシナリオに基づいてこの問題をトラブルシューティングしてください:

  1. 音声は、.mp3 ファイルなどの完全なファイルとして保存されます。

    1. 音声フォーマットの一貫性:リクエストパラメーターで指定された音声フォーマットがファイル拡張子と一致していることを確認してください。例えば、リクエストパラメーターで音声フォーマットが WAV に設定されているのに、ファイル拡張子が .mp3 の場合、再生が失敗する可能性があります。

    2. プレーヤーの互換性:ご使用のプレーヤーが音声ファイルのフォーマットとサンプルレートをサポートしていることを確認してください。例えば、一部のプレーヤーは高いサンプルレートや特定の音声エンコーディングをサポートしていない場合があります。

  2. 音声がストリーミングモードで再生される場合

    1. 音声ストリームを完全なファイルとして保存し、再生を試みてください。ファイルの再生に失敗した場合は、最初のシナリオのトラブルシューティング手順をご参照ください。

    2. ファイルが正しく再生される場合、問題はストリーミング再生の実装にある可能性があります。ご使用のプレーヤーがストリーミング再生をサポートしていることを確認してください。

      ストリーミング再生をサポートする一般的なツールとライブラリには、ffmpeg、pyaudio (Python)、AudioFormat (Java)、MediaSource (JavaScript) があります。

Q:音声の再生が途切れるのはなぜですか?

以下のシナリオに基づいてこの問題をトラブルシューティングしてください:

  1. テキスト送信速度の確認: テキストの送信間隔が合理的であることを確認してください。前のセグメントの音声再生が終了した後に、次のテキストセグメントの送信が遅れないようにしてください。

  2. コールバック関数のパフォーマンスの確認:

    • コールバック関数に過剰なビジネスロジックが含まれており、それがブロックの原因になっていないか確認してください。

    • コールバック関数は WebSocket スレッドで実行されます。このスレッドがブロックされると、WebSocket がネットワークパケットを受信する能力が妨げられ、音声の途切れが発生する可能性があります。

    • WebSocket スレッドのブロックを避けるために、音声データを別の音声バッファーに書き込み、別のスレッドでそれを読み取って処理してください。

  3. ネットワークの安定性の確認: ネットワーク接続が安定していることを確認し、ネットワークの変動による音声伝送の中断や遅延を防いでください。

Q:音声合成が遅い (合成時間が長い) のはなぜですか?

以下のトラブルシューティング手順を実行してください:

  1. 入力間隔の確認

    ストリーミング音声合成を使用している場合、テキストの送信間隔が長すぎないか確認してください。例えば、次のセグメントを送信する前に数秒の遅延があると、総合成時間が増加します。

  2. パフォーマンスメトリックの分析

    • 初回パケット遅延:通常は約 500 ms です。

    • リアルタイム係数 (RTF):総合成時間 / 音声の長さで計算されます。RTF は通常 1.0 未満です。

Q:合成された音声の発音が間違っている場合、どうすればよいですか?

SSML の <phoneme> タグを使用して、正しい発音を指定してください。

Q:なぜ音声が返されないのですか?なぜテキストの末尾が音声に正常に変換されないのですか?(合成音声の欠落)

SpeechSynthesizer クラスstreaming_complete メソッドを呼び出したか確認してください。サーバーはテキストをキャッシュし、十分なテキストを受信した後にのみ合成を開始します。streaming_complete メソッドを呼び出さないと、キャッシュに残っているテキストが合成されない可能性があります。

Q:SSL 証明書の検証失敗をどのように処理しますか?

  1. システムのルート証明書をインストールします。

    sudo yum install -y ca-certificates
    sudo update-ca-trust enable
  2. コードに以下の内容を追加します。

    import os
    os.environ["SSL_CERT_FILE"] = "/etc/ssl/certs/ca-bundle.crt"

Q:macOS で「SSL: CERTIFICATE_VERIFY_FAILED」例外が発生する原因は何ですか?(websocket closed due to [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000))

WebSocket に接続する際、証明書が見つからないというメッセージとともに OpenSSL 証明書の検証失敗が発生することがあります。これは通常、Python 環境の証明書構成が正しくないために発生します。以下の手順に従って、証明書の問題を手動で特定し、修正してください:

  1. システム証明書をエクスポートし、環境変数を設定します。 以下のコマンドを実行して、macOS システムからすべての証明書をファイルにエクスポートし、このファイルを Python および関連ライブラリのデフォルトの証明書パスとして設定します:

    security find-certificate -a -p > ~/all_mac_certs.pem
    export SSL_CERT_FILE=~/all_mac_certs.pem
    export REQUESTS_CA_BUNDLE=~/all_mac_certs.pem
  2. シンボリックリンクを作成して Python の OpenSSL 構成を修正します。 Python の OpenSSL 構成に証明書が欠落している場合は、以下のコマンドを実行してシンボリックリンクを作成します。コマンド内のパスを、ローカルにインストールされている Python バージョンの実際のインストールパスに置き換えてください:

    # 3.9 はサンプルバージョン番号です。ローカルにインストールされている Python バージョンに応じてパスを調整してください。
    ln -s /etc/ssl/* /Library/Frameworks/Python.framework/Versions/3.9/etc/openssl
  3. ターミナルを再起動し、キャッシュをクリアします。 上記の手順を完了したら、ターミナルを閉じて再度開き、環境変数が有効になるようにします。存在する可能性のあるキャッシュをクリアし、再度 WebSocket に接続してみてください。

これらの手順により、不正な証明書構成による接続の問題が解決されるはずです。問題が解決しない場合は、ターゲットサーバーの証明書構成が正しいか確認してください。

Q:コード実行時に「AttributeError: module 'websocket' has no attribute 'WebSocketApp'. Did you mean: 'WebSocket'?」エラーが発生する原因は何ですか?

このエラーは、websocket-client がインストールされていないか、そのバージョンが不一致であるために発生します。以下のコマンドを実行して問題を解決してください:

pip uninstall websocket-client
pip uninstall websocket
pip install websocket-client

権限と認証

Q:API キーを CosyVoice 音声合成サービスのみで使用し、他の Model Studio モデルでは使用しないようにしたいのですが、どうすればよいですか

ワークスペースを作成し、特定のモデルのみを承認することで、API キーの範囲を制限できます。「ワークスペースの管理」をご参照ください。

その他の質問

GitHub の Q&A をご参照ください。