Skip to main content

Qwen-Audio と CosyVoice の音声クローニング Python SDK リファレンス

DashScope Python SDK を使用して Qwen-Audio と CosyVoice の音声をクローンし、管理します。

サービスエンドポイント

SDK のインターフェースアドレスは、Client コンストラクターの workspace/region パラメーターで決まります（下記のアドレスには WorkspaceId が含まれます）。他のリージョンに切り替えるには、Client コンストラクターのパラメーターを対象リージョンの値に変更してください。
  • API キーはリージョンごとに異なります。対象リージョンに対応する API キーを使用してください。
  • リージョン設定は Client レベルの設定であり、その Client のすべての DashScope SDK API 呼び出しに影響します。
  • シンガポール
  • 中国 (北京)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1{WorkspaceId} を実際の ワークスペース ID に置き換えてください。
Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールリージョン向けに、ワークスペース固有の専用ドメインをリリースしました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。新しい専用ドメインへの移行を推奨します。
  • 中国 (北京)： dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com へ
  • シンガポール： dashscope-intl.aliyuncs.com から {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com へ

核心リソース（client.audio.voices）

機能：Qwen-Audio-TTS、Qwen-Audio-Realtime、CosyVoice のクローン音色のライフサイクル (作成、照会、更新、削除) を管理します。

Client 構築（認証とリージョン） 

import os
import dashscope

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

create() — 音声の作成

メソッドシグネチャ： 
def create(self, *, target_model: str, prefix: str, url: str,
           language_hints: List[str] = None,
           max_prompt_audio_length: float = None,
           extra_input: Dict = None,
           parameters: Dict = None, ...) -> Voice
パラメーター：
パラメータータイプ必須説明
target_modelstrはい音色を使用する対象モデル。後続のリクエストでその音色を使用するモデルと一致する必要があります。一致しない場合、リクエストは失敗します。
prefixstrはい音声名のプレフィックス。英数字のみ使用できます。最大長は 10 文字です。生成される音声名は、 {target_model}-{prefix}-{unique_id} という形式になります。
urlstrはい音声クローニングに使用する参照音声。公開アクセス可能な URL または data:audio/wav;base64,... 形式の Base64 Data URI を指定できます。
language_hintsList[str]いいえモデルがサンプル音声の言語を識別し、音声特徴をより正確に抽出してクローニングの品質を向上させるのに役立ちます。指定した言語が実際の音声の言語と一致しない場合 (たとえば、音声が中国語なのに en を設定した場合)、システムはこの値を無視し、言語を自動的に検出します。このパラメーターは配列で、要素数は 1 である必要があります。
対象モデル：qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-plus、cosyvoice-v3-flash。
  • qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash：
    • zh：中国語
    • en：英語
    • fr：フランス語
    • de：ドイツ語
    • ja：日本語
    • ko：韓国語
    • ru：ロシア語
    • pt：ポルトガル語
    • th：タイ語
    • id：インドネシア語
    • vi：ベトナム語
    • it：イタリア語
    • es：スペイン語
    • ms：マレーシア語
    • fil：フィリピン語
    • ar：アラビア語
  • cosyvoice-v3-plus：
    • zh：中国語
    • en：英語
    • fr：フランス語
    • de：ドイツ語
    • ja：日本語
    • ko：韓国語
    • ru：ロシア語
  • cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash：
    • zh：中国語
    • en：英語
    • fr：フランス語
    • de：ドイツ語
    • ja：日本語
    • ko：韓国語
    • ru：ロシア語
    • pt：ポルトガル語
    • th：タイ語
    • id：インドネシア語
    • vi：ベトナム語
デフォルト： ["zh"]。
max_prompt_audio_lengthfloatいいえ前処理後の参照音声の最大長 (秒単位)。有効な値： [3.0, 30.0]。デフォルト： 10.0。
対象モデル：qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。
enable_preprocessboolいいえ音声の前処理 (ノイズリダクション、音質向上、音量正規化) を有効にするかどうか。バックグラウンドノイズのある録音の場合は有効にします。静かな環境での録音の場合は、元の音声特徴を保持するために無効にします。デフォルト： false。
対象モデル：qwen-audio-3.1-tts-plus、qwen-audio-3.1-tts-flash、qwen-audio-3.0-tts-plus、qwen-audio-3.0-tts-flash、qwen-audio-3.1-realtime-plus、qwen-audio-3.0-realtime-plus、qwen-audio-3.0-realtime-flash、cosyvoice-v3.5-plus、cosyvoice-v3.5-flash、cosyvoice-v3-flash。
enable_volume_normalizationboolいいえ音声クローニングに使用されるサンプル音声の音量を正規化するかどうかを指定します。このパラメーターはキーワード引数として直接渡します。デフォルト値： False。このパラメーターを True に設定した場合、作成された音声で合成されるオーディオの音量は、このパラメーターを無効にした場合と異なる可能性があります。
戻り値： Voice オブジェクト。voice_id が音声 ID、request_id がリクエスト ID です。

list() — 音声のリスト表示

メソッドシグネチャ： 
def list(self, *, prefix: str = None, page_index: int = 0, page_size: int = 10, ...) -> VoiceList
パラメーター：
パラメータータイプ必須説明
prefixstrいいえ音声名のプレフィックスでフィルタリングします。
page_indexintいいえページインデックス。デフォルト： 0。
page_sizeintいいえページサイズ。デフォルト： 10。
戻り値： VoiceList オブジェクト。voices が音声リスト、request_id がリクエスト ID です。

get() — 音声詳細の照会

メソッドシグネチャ： 
def get(self, voice_id: str, ...) -> Voice
パラメーター：
パラメータータイプ必須説明
voice_idstrはい照会対象の音声 ID。
戻り値： Voice オブジェクト（音声の詳細）。

update() — 音声の更新

メソッドシグネチャ： 
def update(self, voice_id: str, *, url: str, ...) -> JobStatus
パラメーター：
パラメータータイプ必須説明
voice_idstrはい更新対象の音声 ID。
urlstrはい新しい参照音声。公開アクセス可能な URL または data:audio/wav;base64,... 形式の Base64 Data URI を指定できます。

delete() — 音声の削除

メソッドシグネチャ： 
def delete(self, voice_id: str, ...) -> JobStatus
パラメーター：
パラメータータイプ必須説明
voice_idstrはい削除対象の音声 ID。

コード例

音声の作成 

import os
import dashscope

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

TARGET_MODEL = 'qwen-audio-3.1-tts-plus'
voice_prefix = 'myvoice'
url = 'https://your-audio-file-url'

# 頻繁な呼び出しは避けてください。呼び出しごとに新しい音声が作成され、クォータ制限に達するとそれ以上の作成はできなくなります。
voice = client.audio.voices.create(
    target_model=TARGET_MODEL,
    prefix=voice_prefix,
    url=url,
    max_prompt_audio_length=10,
    # extra_input={'enable_preprocess': False, 'enable_volume_normalization': True}
)

print(f"Request ID: {voice.request_id}")
print(f"Voice ID: {voice.voice_id}")
ローカルの WAV ファイルを使用する場合は、上記の url への代入を以下のコードに置き換えてから create を呼び出します。音声の更新時も、Data URI を update の url パラメーターに指定します。sample.wav をローカル音声ファイルのパスに置き換えてください。 
import base64
from pathlib import Path

url = "data:audio/wav;base64," + base64.b64encode(
    Path("sample.wav").read_bytes()
).decode("ascii")

音声のリスト表示 

import os
import dashscope

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

# プレフィックスでフィルタリングします。None を指定すると、すべての音声がリストされます。
voices = client.audio.voices.list(prefix='myvoice', page_index=0, page_size=10)

print(f"Request ID: {voices.request_id}")
print(f"Found voices: {voices.voices}")

特定音声の照会 

import os
import dashscope

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

voice_id = 'qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx'

voice_details = client.audio.voices.get(voice_id=voice_id)

print(f"Request ID: {voice_details.request_id}")
print(f"Voice Details: {voice_details}")

音声の更新 

import os
import dashscope

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

result = client.audio.voices.update(
    voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Update submitted. Request ID: {result.request_id}")

音声の削除 

import os
import dashscope

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

result = client.audio.voices.delete(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Deletion submitted. Request ID: {result.request_id}")