音声クローニング HTTP API：Qwen-Audio と CosyVoice

このリファレンスは Qwen-Audio-TTS、Qwen-Audio-Realtime、CosyVoice を対象とします。まず API キーを取得し、環境変数を設定します。リクエスト例は DASHSCOPE_API_KEY を読み取ります。複数の API で同じ音声を管理する場合は、同じアカウントを使用します。 SDK の定義については、Java SDK と Python SDK を参照してください。

サービスエンドポイント

中国（北京）
シンガポール

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization

{WorkspaceId} を実際のワークスペース ID に置き換えます。Alibaba Cloud Model Studio コンソールの Workspace Details ページで確認できます。北京とシンガポールでは API キーが異なります。

Alibaba Cloud Model Studio は、中国 (北京) およびシンガポールの各リージョン向けにワークスペース固有ドメインをリリースしました。これらの新しい専用ドメインにより、推論リクエストのパフォーマンスと安定性が向上します。以下の新しいドメインへの移行を推奨します：

中国（北京）リージョン：dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com に移行します。
シンガポールリージョン：dashscope-intl.aliyuncs.com から {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com に移行します。

既存のドメインも引き続きすべて利用できます。

リクエストヘッダー

パラメーター	タイプ	必須	説明
Authorization	string	はい	認証トークン。フォーマットは `Bearer <your_api_key>` です。`<your_api_key>` を実際の API キーに置き換えます。
Content-Type	string	はい	`application/json` に設定します。

音声の要件と料金

音声要件は、音声クローニングユーザーガイドをご覧ください。Qwen-Audio-Realtime のクローニング手順は、リアルタイム音声対話の音声クローニングで説明します。Qwen-Audio-Realtime の音声作成は無料です。モデル呼び出しは対象モデルに従って課金されます。詳細は課金情報、数量制限はクォータ情報をご覧ください。

リクエスト本文

model string — 必須voice-enrollment に設定します。input object — 必須

プロパティ

action string — 必須操作：

create_voice: 音声を作成します。
list_voice: 音声の一覧を取得します。
query_voice: 音声の詳細を取得します。
update_voice: 音声を更新します。
delete_voice: 音声を削除します。

target_model string — 作成時に必須音声を使用する対象モデルです。後続の合成または会話の呼び出しで使用するモデルと一致する必要があります。一致しない場合、呼び出しは失敗します。音声クローニングに対応する Qwen-Audio-TTS、Qwen-Audio-Realtime、CosyVoice のモデルを選択してください。モデル ID とリージョンは対応モデルを参照してください。audio string — 作成または更新時に url を指定しない場合は必須作成時の参照音声、または更新時の新しい参照音声です。公開アクセス可能な URL、または data:audio/wav;base64,... などの Base64 Data URI を指定できます。

従来のパラメーター url と互換性があります。url を使用する場合は audio を省略できます。url は段階的に廃止されるため、audio への切り替えを推奨します。

prefix string — 作成時に必須、一覧取得時は任意作成時：音声名のプレフィックスです。数字と英字のみ使用でき、最大 10 文字です。生成される音声名の形式は {target_model}-{prefix}-{unique_id} です。一覧取得時：名前のプレフィックスで音声を絞り込みます。language_hints array[string] — 作成時は任意サンプル音声の言語を補助的に識別し、声の特徴をより正確に抽出してクローニングの品質を高めます。指定した言語と実際の音声の言語が異なる場合（中国語音声に 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.1-realtime-flash、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.1-realtime-flash、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_length float — 作成時は任意前処理後に音声クローニングで使用する参照音声の最大長（秒）。値の範囲：[3.0, 30.0]。デフォルト値：10.0。

enable_preprocess boolean — 作成時は任意音声の前処理（ノイズ除去、音声強調、音量の正規化）を有効にするかどうかです。背景ノイズがある録音では有効にします。静かな環境の録音では、元の声の特徴を保つため無効にします。デフォルト：false。

enable_volume_normalization string — 作成時は任意音声クローニング用のサンプル音声の音量を正規化するかどうかです。値：

"true"：音量正規化を有効にします。
"false"：音量の正規化を無効にします。

有効にすると、作成した音声で合成する音声の音量が、無効にした場合と異なることがあります。デフォルト値："false"。page_index integer — 一覧取得時は任意ページのインデックス。page_size integer — 一覧取得時は任意1 ページあたりの件数。voice_id string — 詳細取得、更新、削除時に必須詳細取得、更新、削除の対象となる音声 ID です。

リクエストの例

作成
一覧取得
詳細取得
更新
削除

例では qwen-audio-3.1-tts-plus を使用します。input 内の target_model を実際の対象モデル ID に置き換えてください。次の設定はシンガポールリージョン用です。「{WorkspaceId}」を実際のワークスペース ID に置き換えます。設定はリージョンによって異なります。

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "qwen-audio-3.1-tts-plus",
        "prefix": "myvoice",
        "audio": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'

ローカル WAV 音声ファイルを使用する場合は、次のコードで Base64 Data URI を生成し、作成または更新リクエストの input オブジェクトの audio フィールドに audio の値を設定できます。sample.wav をローカル音声ファイルのパスに置き換えます。

import base64
from pathlib import Path

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

次の設定はシンガポールリージョン用です。「{WorkspaceId}」を実際のワークスペース ID に置き換えます。設定はリージョンによって異なります。

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "list_voice",
        "prefix": "myvoice",
        "page_size": 10,
        "page_index": 0
    }
}'

次の設定はシンガポールリージョン用です。「{WorkspaceId}」を実際のワークスペース ID に置き換えます。設定はリージョンによって異なります。

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "query_voice",
        "voice_id": "yourVoiceId"
    }
}'

次の設定はシンガポールリージョン用です。「{WorkspaceId}」を実際のワークスペース ID に置き換えます。設定はリージョンによって異なります。

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "update_voice",
        "voice_id": "yourVoiceId",
        "audio": "https://new-audio-url.wav"
    }
}'

次の設定はシンガポールリージョン用です。「{WorkspaceId}」を実際のワークスペース ID に置き換えます。設定はリージョンによって異なります。

curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'

レスポンス本文

request_id stringこのリクエストの一意の識別子。output object作成、一覧取得、詳細取得の各操作に対応するフィールドを含みます。更新では業務データを返しません。レスポンスに空のオブジェクトである preview_audio が含まれる場合がありますが、無視できます。削除では空のオブジェクトを返します。

プロパティ

voice_id string — 作成時に返却音声 ID。voice_list array[object] — 一覧取得時に返却見つかった音声の一覧。

プロパティ

voice_id string音声 ID。gmt_create string音声の作成日時。gmt_modified string最終更新日時。status string音声のステータス。有効値は「音声のステータスの説明」をご覧ください。

resource_link string — 詳細取得時に返却音声ファイルの URL。gmt_create string — 詳細取得時に返却音声の作成日時。gmt_modified string — 詳細取得時に返却最終更新日時。status string — 詳細取得時に返却音声のステータス。有効値は「音声のステータスの説明」をご覧ください。target_model string — 詳細取得時に返却音声を使用する対象モデル（テキスト音声合成またはリアルタイム音声対話）。

usage objectこのリクエストの使用量情報。

プロパティ

count integer常に 1 です。音声作成時は、作成した音声の数を示します。

レスポンスの例

作成
一覧取得
詳細取得
更新
削除

{
    "output": {
        "voice_id": "qwen-audio-3.1-tts-plus-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

{
    "output": {
        "voice_list": [
            {
                "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx",
                "gmt_create": "2024-12-11 13:38:02",
                "gmt_modified": "2024-12-11 13:38:02",
                "status": "OK"
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

{
    "output": {
        "gmt_create": "2024-12-11 13:38:02",
        "resource_link": "https://yourAudioFileUrl",
        "target_model": "qwen-audio-3.1-tts-plus",
        "gmt_modified": "2024-12-11 13:38:02",
        "status": "OK"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

音声ステータスの説明

作成した音声は審査されます。

ステータス	説明
DEPLOYING	審査中または処理中です。
OK	審査に合格しました。音声は使用可能です。
UNDEPLOYED	審査が拒否されました。音声は使用できません。

エラーメッセージ

エラーが発生した場合は、エラーコードを参照して対処してください。

​サービスエンドポイント

​リクエストヘッダー

​音声の要件と料金

​リクエスト本文

リクエストの例

​レスポンス本文

レスポンスの例

​音声ステータスの説明

​エラーメッセージ

サービスエンドポイント

リクエストヘッダー

音声の要件と料金

リクエスト本文

レスポンス本文

音声ステータスの説明

エラーメッセージ