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

Alibaba Cloud Model Studio:CosyVoice 音声合成 Python SDK

最終更新日:Mar 02, 2026

本トピックでは、CosyVoice 音声合成 Python SDK のパラメーターおよびメソッドについて説明します。

ユーザーガイド: モデルの概要および選択推奨事項については、「リアルタイム音声合成 – CosyVoice/Sambert」をご参照ください。

前提条件

  • Model Studio を有効化し、API キーを作成済みである必要があります。セキュリティリスクを防止するため、API キーをコード内にハードコーディングせず、環境変数としてエクスポートしてください。

    説明

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

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

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

  • DashScope SDK の最新版をインストールします。

モデルおよび料金

詳細については、「リアルタイム音声合成 – CosyVoice/Sambert」をご参照ください。

音声合成におけるテキストの制限およびフォーマット要件

テキスト長の制限

文字数計算ルール

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

  • SSML タグの内容はテキスト長の計算対象外です。

  • 例:

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

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

    • "Chinese." → 2(zhong)+2(wen)+1(句点)=5 文字

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

    • "<speak>Hello</speak>" → 2(ni)+2(hao)=4 文字

エンコード形式

UTF-8 エンコードを使用します。

数式のサポート

数式のパースは、cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 モデルのみでサポートされています。小学校および中学校で一般的に使用される数式(基本演算、代数、幾何学など)をサポートします。

詳細については、「LaTeX 数式から音声へ」をご参照ください。

音声合成マークアップ言語 (SSML) のサポート

音声合成マークアップ言語 (SSML) 機能は、cosyvoice-v3-flash、cosyvoice-v3-plus、および cosyvoice-v2 モデルのクローン音声、および音声一覧で「対応」と明記されたシステム音声でのみ利用可能です。この機能を利用するには、以下の条件を満たす必要があります:

クイックスタート

SpeechSynthesizer クラスは、コアとなる音声合成メソッドを提供し、以下の呼び出しタイプをサポートします:

  • 非ストリーミング呼び出し:ブロッキング方式。テキスト全体を一度に送信し、完全な音声応答を即座に受信します。短文の音声合成に適しています。

  • 片方向ストリーミング呼び出し:ノンブロッキング方式。テキスト全体を一度に送信し、コールバック関数経由で音声データ(分割されている可能性あり)を受信します。リアルタイム性が高く、短文の音声合成に適しています。

  • 双方向ストリーミング呼び出し:ノンブロッキング方式。テキストを複数のセグメントに分割して送信し、コールバック関数経由でリアルタイムに合成された音声ストリームを段階的に受信します。リアルタイム性が高く、長文の音声合成に適しています。

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

コールバック関数を指定せずに単一の音声合成タスクを送信できます。結果は中間ストリーミング出力なしで一度に返されます。

image

SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターをバインドした後、call メソッドを呼び出して音声合成を行い、バイナリ音声データを取得します。

テキストは 20,000 文字を超えてはなりません。詳細については、SpeechSynthesizer クラスcall メソッドをご参照ください。

重要

call メソッドを呼び出す前に、SpeechSynthesizer インスタンスを再初期化してください。

完全な例を表示

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import os

# API キーはシンガポールリージョンと北京リージョンで異なります。API キーの取得方法:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio の API キーに置き換えてください:dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# この URL はシンガポールリージョン向けです。北京リージョン向けには、wss://dashscope.aliyuncs.com/api-ws/v1/inference に置き換えてください。
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

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

# SpeechSynthesizer をインスタンス化し、コンストラクター内で model および voice などのリクエストパラメーターを渡します。
synthesizer = SpeechSynthesizer(model=model, voice=voice)
# テキストを合成に送信し、バイナリ音声を取得します。
audio = synthesizer.call("今日の天気はどうですか?")
# 最初のリクエストでは WebSocket 接続が確立されるため、最初のパッケージ遅延には接続確立時間が含まれます。
print('[Metric] requestId: {}, first-package delay: {} 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 メソッド経由でリアルタイムに合成結果を受信します。

テキストは 20,000 文字を超えてはなりません。詳細については、SpeechSynthesizer クラスcall メソッドをご参照ください。

重要

call メソッドを呼び出す前に、SpeechSynthesizer インスタンスを再初期化してください。

完全な例を表示

# coding=utf-8

import os
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 キーはシンガポールリージョンと北京リージョンで異なります。API キーの取得方法:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio の API キーに置き換えてください:dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# この URL はシンガポールリージョン向けです。北京リージョン向けには、wss://dashscope.aliyuncs.com/api-ws/v1/inference に置き換えてください。
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

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


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

    def on_open(self):
        self.file = open("output.mp3", "wb")
        print("Connection established: " + get_timestamp())

    def on_complete(self):
        print("Speech synthesis completed. All results received: " + get_timestamp())
        # on_complete がトリガーされた後に get_first_package_delay を呼び出します。
        # 最初のリクエストでは WebSocket 接続が確立されるため、最初のパッケージ遅延には接続確立時間が含まれます。
        print('[Metric] requestId: {}, first-package delay: {} ms'.format(
            synthesizer.get_last_request_id(),
            synthesizer.get_first_package_delay()))

    def on_error(self, message: str):
        print(f"Speech synthesis error: {message}")

    def on_close(self):
        print("Connection closed: " + get_timestamp())
        self.file.close()

    def on_event(self, message):
        pass

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " Binary audio length: " + str(len(data)))
        self.file.write(data)


callback = Callback()

# SpeechSynthesizer をインスタンス化し、コンストラクター内で model および voice などのリクエストパラメーターを渡します。
synthesizer = SpeechSynthesizer(
    model=model,
    voice=voice,
    callback=callback,
)

# コールバックインターフェイスの on_data メソッド経由でリアルタイムにバイナリ音声を取得するためにテキストを合成に送信します。
synthesizer.call("今日の天気はどうですか?")

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

単一の音声合成タスク内でテキストを断片的に送信し、コールバック経由でリアルタイムに結果を受信できます。

説明
  • ストリーミング入力中に、streaming_call を複数回呼び出して、順番にテキスト断片を送信できます。サーバーが自動的にこれらを文に分割します。

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

    • 不完全な文は、完全になるまでバッファーに保持され、その後合成されます。

    streaming_complete を呼び出すと、サーバーは受信済みだが未処理のすべての断片(不完全な文を含む)を強制的に合成します。

  • テキスト断片の送信間隔は 23 秒を超えてはなりません。超えると「23 秒経過後のリクエストタイムアウト」エラーが返されます。

    これ以上送信するテキストがない場合は、タスクを終了するために速やかに streaming_complete メソッドを呼び出してください。

    サーバーは固定の 23 秒タイムアウトを適用します。クライアント側でこの設定を変更することはできません。
image
  1. SpeechSynthesizer クラスのインスタンス化

    SpeechSynthesizer クラスをインスタンス化し、リクエストパラメーターおよびコールバックインターフェイス (ResultCallback)をバインドします。

  2. ストリーミング

    SpeechSynthesizer クラスstreaming_call メソッドを複数回呼び出して、合成用のテキスト断片を送信します。

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

    streaming_call メソッド(text パラメーター)への各送信は 20,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 os
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 キーはシンガポールリージョンと北京リージョンで異なります。API キーの取得方法:https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# 環境変数を設定していない場合は、次の行を Model Studio の API キーに置き換えてください:dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# この URL はシンガポールリージョン向けです。北京リージョン向けには、wss://dashscope.aliyuncs.com/api-ws/v1/inference に置き換えてください。
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

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


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

    def on_open(self):
        print("Connection established: " + 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("Speech synthesis completed. All results received: " + get_timestamp())

    def on_error(self, message: str):
        print(f"Speech synthesis error: {message}")

    def on_close(self):
        print("Connection closed: " + 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() + " Binary audio length: " + str(len(data)))
        self._stream.write(data)


callback = Callback()

test_text = [
    "ストリーミング音声合成 SDK は、",
    "入力テキストを",
    "バイナリ音声データに変換します。",
    "非ストリーミング TTS と比較して、",
    "ストリーミング TTS はリアルタイム性が優れています。",
    "ユーザーはテキストを入力する際にほぼ同期した音声出力を聞き取ることができ、",
    "インタラクションの向上と待機時間の短縮を大幅に実現します。",
    "大規模言語モデル(LLM)のシナリオに最適で、",
    "テキストが音声合成のためにストリーミングされます。",
]

# SpeechSynthesizer をインスタンス化し、コンストラクター内で model および voice などのリクエストパラメーターを渡します。
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('[Metric] requestId: {}, first-package delay: {} 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)」機能でカスタマイズ。クローン音声の音色を使用する際は、音声クローン作成と音声合成で同じアカウントを使用する必要があります。手順の詳細については、「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 キーを実際のキーに置き換えてください。
# dashscope.api_key = "your-api-key"

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("Connection established: " + get_timestamp())

    def on_complete(self):
        print("Speech synthesis completed. All results received: " + get_timestamp())

    def on_error(self, message: str):
        print(f"Speech synthesis error: {message}")

    def on_close(self):
        print("Connection closed: " + 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': 'T', 'begin_index': 0, 'end_index': 1, 'begin_time': 80, 'end_time': 200}

    def on_data(self, data: bytes) -> None:
        print(get_timestamp() + " Binary audio length: " + str(len(data)))
        self.file.write(data)


callback = Callback()

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

# コールバックインターフェイスの on_data メソッド経由でリアルタイムにバイナリ音声を取得するためにテキストを合成に送信します。
synthesizer.call("今日の天気はどうですか?")
# 最初のリクエストでは WebSocket 接続が確立されるため、最初のパッケージ遅延には接続確立時間が含まれます。
print('[Metric] requestId: {}, first-package delay: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

seed

int

いいえ

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

デフォルト値:0。

範囲:[0, 65535]。

language_hints

list[str]

いいえ

音声合成の対象言語を指定し、合成品質を向上させます。

数字、略語、記号の発音や少数言語の合成効果が期待通りでない場合に使用します。例:

  • 数字の予期しない発音:「hello, this is 110」が「hello, this is one one zero」と読み上げられ、期待通りの「hello, this is yao yao ling」にならない場合。

  • 記号の不正確な発音:「@」が「ait」と読み上げられ、「at」とならない場合。

  • 少数言語の合成品質が低く、不自然な合成になる場合。

範囲:

  • zh:中国語

  • en:英語

  • fr:フランス語

  • de:ドイツ語

  • ja:日本語

  • ko:韓国語

  • ru:ロシア語

注記:このパラメーターは配列ですが、現在のバージョンでは先頭の要素のみが処理されます。そのため、1 つの値のみを渡してください。

重要

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

instruction

str

いいえ

方言、感情、役割などの合成効果を制御する命令を設定します。この機能は、cosyvoice-v3-flash モデルのクローン音声、および音声一覧で「Instruct 対応」と明記されたシステム音声でのみ適用されます。

長さ制限:100 文字。

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

使用要件(モデルごとに異なります):

  • cosyvoice-v3-flash:以下の要件に従ってください:

    • クローン音声:自然言語を用いて音声合成効果を制御できます。

      命令の例:

      広東語で話してください。(対応する方言:広東語、東北弁、甘粛弁、貴州弁、河南弁、湖北弁、江西弁、閩南弁、寧夏弁、山西弁、陝西弁、山東弁、上海弁、四川弁、天津弁、雲南弁)
      できるだけ大きな声で話してください。
      できるだけゆっくり話してください。
      できるだけ早く話してください。
      とても小さな声で話してください。
      もう少しゆっくり話してもらえますか?
      もっとずっと早く話してもらえますか?
      もっとずっとゆっくり話してもらえますか?
      もう少し早く話してもらえますか?
      とても怒ったトーンで話してください。
      とても幸せなトーンで話してください。
      とても恐れたトーンで話してください。
      とても悲しいトーンで話してください。
      とても驚いたトーンで話してください。
      決意の感じを示すようにしてください。
      怒りの感じを示すようにしてください。
      フレンドリーなトーンで話してください。
      冷たいトーンで話してください。
      威厳あるトーンで話してください。
      自然なトーンを体験したいです。
      脅威を表現する様子を見たいです。
      知恵を表現する様子を見たいです。
      誘惑を表現する様子を見たいです。
      生き生きとしたトーンで話してほしいです。
      情熱的なトーンで話してほしいです。
      冷静で落ち着いたトーンで話してほしいです。
      自信に満ちたトーンで話してほしいです。
      興奮した感情でコミュニケーションを取ってもらえますか?
      傲慢な感情表現を示してもらえますか?
      エレガントな感情を示してもらえますか?
      喜んだトーンで質問に答えてもらえますか?
      優しい感情でデモンストレーションしてもらえますか?
      冷静なトーンで話してもらえますか?
      深遠なトーンで答えてもらえますか?
      荒々しい感情態度で話してもらえますか?
      邪悪なトーンでこの答えを教えてください。
      しなやかなトーンでこの答えを教えてください。
      自然でフレンドリーな会話スタイルで語ってください。
      ラジオドラマのポッドキャスターのトーンで話してください。
    • システム音声のトーン:命令は固定のフォーマットおよび内容でなければなりません。詳細については、「音声トーン一覧」をご参照ください。

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"})

hot_fix

dict

いいえ

特定の単語の発音をカスタマイズしたり、合成対象のテキストを置き換えたりするためのテキストホットフィックス構成です。この機能は、cosyvoice-v3-flash のクローン音声でのみサポートされます。

パラメーター:

  • pronunciation:発音をカスタマイズ。誤ったデフォルト発音を修正するために、単語のピンインを指定します。

  • replace:テキスト置換。合成前に指定された単語を目的のテキストに置き換えます。置換後のテキストが実際の合成入力になります。

例:

synthesizer = SpeechSynthesizer(
    model="cosyvoice-v3-flash",
    voice="your_voice", # cosyvoice-v3-flash のクローン音声に置き換えてください
    hot_fix={
        "pronunciation": [{"weather": "tian1 qi4"}],
        "replace": [{"today": "jin1 tian1"}]
    }
)

enable_markdown_filter

bool

いいえ

Markdown フィルターを有効化します。有効化すると、システムが合成前に入力テキストから Markdown 記号を自動的にフィルターし、それらがテキスト内容として読み上げられるのを防ぎます。この機能は、cosyvoice-v3-flash のクローン音声でのみサポートされます。

デフォルト:False。

値:

  • True:Markdown フィルターを有効化。

  • False:Markdown フィルターを無効化。

説明

enable_markdown_filteradditional_params パラメーターを使用して設定します:

synthesizer = SpeechSynthesizer(
    model="cosyvoice-v3-flash",
    voice="your_voice", # cosyvoice-v3-flash のクローン音声に置き換えてください
    additional_params={"enable_markdown_filter": True}
)

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 インスタンスを作成する際のケースは以下のとおりです:

重要

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

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

このメソッドは N ミリ秒(complete_timeout_millis で設定)スレッドをブロックします。completeTimeoutMillis が 0 の場合、無期限に待ちます。

デフォルトでは、10 分後に待機を停止します。

双方向ストリーミング呼び出し」をご参照ください。

重要

双方向ストリーミング呼び出しでは、必ずこのメソッドを呼び出してください。呼び出さないと、合成された音声が欠落する可能性があります。

def get_last_request_id(self)

なし

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

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

def get_first_package_delay(self)

なし

最初のパッケージ遅延

タスク終了後に、現在のタスクの最初のパッケージ遅延を取得します。最初のパッケージ遅延は、テキスト送信から最初の音声パッケージ受信までの時間をミリ秒単位で表します。

最初のパッケージ遅延に影響を与える要因:

  • WebSocket 接続確立時間(最初の呼び出し)

  • 音声の読み込み時間(音声によって異なる)

  • サービス負荷(ピーク時刻にはキューイングが発生する可能性あり)

  • ネットワーク遅延

典型的な遅延範囲:

  • 既に読み込まれている音声で接続を再利用する場合:約 500 ms

  • 最初の接続または音声切り替えの場合:1500–2000 ms に達する可能性あり

最初のパッケージ遅延が高すぎる場合(>2000 ms)、以下の対策を検討してください:

  1. 高並行シナリオでは、接続プール機能を使用して、事前に接続を確立します。

  2. ネットワーク接続の品質を確認します。

  3. ピーク時刻の呼び出しを避けてください。

def get_response(self)

なし

最後のメッセージ

最後のメッセージ(JSON 形式)を取得します。タスク失敗エラーの検出に役立ちます。

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

片方向ストリーミング呼び出しまたは双方向ストリーミング呼び出しでは、サーバーがステータス情報およびデータをコールバック経由で返します。サーバーの応答を処理するために、コールバックメソッドを実装する必要があります。

このインターフェイスは、from dashscope.audio.tts_v2 import * を使用してインポートできます。

例を表示

class Callback(ResultCallback):
    def on_open(self) -> None:
        print('Connected')
    
    def on_data(self, data: bytes) -> None:
        # バイナリ音声データを処理

    def on_complete(self) -> None:
        print('Completed')

    def on_error(self, message) -> None:
        print('Error:', message)

    def on_close(self) -> None:
        print('Connection closed')


callback = Callback()

メソッド

パラメーター

戻り値

説明

def on_open(self) -> None

なし

なし

サーバーへの接続直後に呼び出されます。

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

message:サーバーからの応答

なし

サーバーが応答したときに呼び出されます。message は JSON 文字列です。これを解析して、タスク ID(task_id)およびこのリクエストの課金対象文字数(characters)を取得できます。

def on_complete(self) -> None

なし

なし

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

def on_error(self, message) -> None

message:エラーメッセージ

なし

エラーが発生したときに呼び出されます。

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

data:サーバーからのバイナリ音声データ

なし

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

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

重要
  • ストリーミング音声合成では、MP3/Opus などの圧縮フォーマットにおいて、セグメント化された音声の送信にはストリーミングプレーヤーが必要です。フレームごとに再生するとデコード失敗を招くため、避けてください。

    ストリーミング再生に対応するプレーヤー:ffmpeg、pyaudio(Python)、AudioFormat(Java)、MediaSource(Javascript)など。
  • 音声データを完全な音声ファイルに結合する場合、追記モードで同じファイルに書き込んでください。

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

def on_close(self) -> None

なし

なし

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

応答

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

エラーコード

エラーが発生した場合は、「エラーメッセージ」を参照してトラブルシューティングを行ってください。

その他のサンプル

その他のサンプルについては、「GitHub」をご参照ください。

よくある質問

機能、課金、およびレート制限

Q:発音が不正確な場合、どのような解決策を試せますか?

SSML を使用して音声合成効果をカスタマイズできます。

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

取得方法はログの有効/無効に依存します:

  1. ログが無効な場合

  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 を取得するにはどうすればよいですか?

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

Q:なぜ SSML が失敗しますか?

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

  1. すべての制限および制約を満たしているか確認します。

  2. DashScope SDK の最新版をインストールします。

  3. 正しいメソッドを使用しているか確認します。SpeechSynthesizer クラスcall メソッドのみが SSML をサポートします。

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

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

各シナリオごとに以下のようにトラブルシューティングを行ってください:

  1. シナリオ:完全なファイルとして保存された音声(例:xx.mp3)

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

    2. プレーヤーの互換性:プレーヤーが音声ファイルのフォーマットおよびサンプルレートをサポートしているか確認します。一部のプレーヤーは高いサンプルレートまたは特定の音声エンコーディングをサポートしていない場合があります。

  2. シナリオ:ストリーミング音声再生

    1. 音声ストリームを完全なファイルとして保存し、プレーヤーで再生を試みます。ファイルが再生できない場合は、シナリオ 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 の「QA」をご参照ください。