Skip to main content

音声デザイン API リファレンス

Voice Design HTTP API を使用して、カスタム音声の作成、一覧表示、照会、および削除を行います。

ユーザーガイド： Voice Design。

エンドポイント

  • 中国 (北京)
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization{WorkspaceId} は、実際の ワークスペース ID に置き換えてください。
Alibaba Cloud Model Studio では、中国 (北京) リージョン向けにワークスペース専用ドメインがリリースされました。新しい専用ドメインは、推論リクエストに対して優れたパフォーマンスと高い安定性を提供します。以下の新しいドメインへの移行を推奨します。
  • 中国 (北京)： dashscope.aliyuncs.com から {WorkspaceId}.cn-beijing.maas.aliyuncs.com へ
{WorkspaceId} は、実際の ワークスペース ID に置き換えてください。既存のドメインは引き続き完全に機能します。

リクエストヘッダー

パラメーター

タイプ

必須

説明

Authorization

string

Yes

Bearer <your_api_key> 形式の認証トークン。<your_api_key> は、実際の API キーに置き換えてください。

Content-Type

string

Yes

リクエストボディのメディアタイプ。application/json に設定します。

音声の作成

リクエストボディ

modelstring（必須）音声デザインモデル。有効な値は次のとおりです。
  • voice-enrollment： CosyVoice 音声デザイン。
inputobject（必須）入力パラメーターオブジェクト。

プロパティ

action string（必須）操作タイプ。
  • CosyVoice（voice-enrollment）： create_voice に設定します。
target_model string（必須）音声を駆動する音声合成（TTS）モデル。この値は、TTS API を呼び出す際に使用するモデルと一致している必要があります。一致しない場合、合成が失敗します。voice_prompt string（必須）目的の音声特性を記述したテキスト。中国語と英語のみサポートされています。
  • CosyVoice（voice-enrollment）： 最大 500 文字。
preview_text string（必須）プレビューオーディオ用のテキスト。
  • CosyVoice（voice-enrollment）： 最大 200 文字。中国語と英語をサポートしています。
prefix string（必須）
CosyVoice（モデルが voice-enrollment の場合）にのみ適用されます。
音声名のプレフィックス。英数字のみ使用可能で、最大 10 文字です。生成される音声名は次の形式になります：{target_model}-vd-{prefix}-{unique_id}language_hints array[string]（任意）
CosyVoice（モデルが voice-enrollment の場合）にのみ適用されます。
生成される音声の言語ヒント。これにより、音声の言語特性や発音パターンが決定されます。ユースケースに合った言語を設定してください。指定された言語は、preview_text の言語と一致している必要があります。現在、最初の要素のみが使用されます。有効な値：
  • zh： 中国語
  • en： 英語
デフォルト： ["zh"]。
parametersobject（任意）音声デザインの設定。

プロパティ

sample_rate int（任意）プレビューオーディオのサンプルレート（Hz 単位）。
  • CosyVoice： 16000、24000、または 48000。
デフォルト： 24000。response_format string（任意）プレビューオーディオのフォーマット。
  • CosyVoice： pcm、wav、または mp3。
デフォルト： wav。
以下の例では中国 (北京) リージョンの設定を使用します。{WorkspaceId} を実際のワークスペース ID に置き換えてください。
curl -X POST https://{WorkspaceId}.cn-beijing.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": "cosyvoice-v3.5-plus",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "prefix": "announcer",
        "language_hints": ["en"]
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

レスポンスボディ

request_idstringこのリクエストの一意な識別子。outputobjectモデルによって返されるデータ。

プロパティ

voice_idstring音声 ID。TTS API の voice パラメーターに指定します。preview_audioobjectプレビューオーディオデータ。

プロパティ

data stringBase64 エンコードされたプレビューオーディオデータ。sample_rate intプレビューオーディオのサンプルレート（Hz 単位）。response_format stringプレビューオーディオのフォーマット。
target_modelstring音声を駆動する TTS モデル。
usageobjectこのリクエストの使用量情報。

プロパティ

count integer作成された音声の数。常に 1。
{
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "cosyvoice-v3.5-plus",
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

音声の一覧表示

リクエストボディ

modelstring（必須）音声デザインモデル。有効な値は次のとおりです。
  • voice-enrollment： CosyVoice 音声デザイン。
inputobject（必須）入力パラメーターオブジェクト。

プロパティ

action string（必須）次の値に設定します： list_voice。prefix string（任意）
CosyVoice のみに適用されます。
音声名のプレフィックスでフィルタリングします。page_index integer（任意）ページインデックス。page_size integer（任意）1 ページあたりのエントリ数。
以下の例では中国 (北京) リージョンの設定を使用します。{WorkspaceId} を実際のワークスペース ID に置き換えてください。
curl -X POST https://{WorkspaceId}.cn-beijing.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
    }
}'

レスポンスボディ

request_idstringこのリクエストの一意な識別子。outputobjectモデルによって返されるデータ。

プロパティ

voice_listarray[object]クエリによって返された音声のリスト。

プロパティ

voice_idstring音声 ID。TTS API の voice パラメーターに指定します。gmt_createstring作成時刻。gmt_modifiedstring最終更新時刻。statusstring
CosyVoice のみが返します。
音声のステータス。有効な値については、「音声ステータスリファレンス」をご参照ください。voice_promptstring音声の説明テキスト。preview_textstringプレビューオーディオのテキスト。
usageobjectこのリクエストの使用量情報。

プロパティ

count integer常に 1。
{
    "output": {
        "voice_list": [
            {
                "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
                "gmt_create": "2025-12-10 14:54:09",
                "gmt_modified": "2025-12-10 17:47:48",
                "status": "OK",
                "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
                "preview_text": "Dear listeners, hello everyone. Welcome to the evening news."
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

音声詳細の照会

リクエストボディ

modelstring（必須）音声デザインモデル。有効な値は次のとおりです。
  • voice-enrollment： CosyVoice 音声デザイン。
inputobject（必須）入力パラメーターオブジェクト。

プロパティ

action string（必須）次の値に設定します： query_voice。voice_id string（必須）
CosyVoice のみに適用されます。
照会する音声 ID。
以下の例では中国 (北京) リージョンの設定を使用します。{WorkspaceId} を実際のワークスペース ID に置き換えてください。
curl -X POST https://{WorkspaceId}.cn-beijing.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"
    }
}'

レスポンスボディ

request_idstringこのリクエストの一意な識別子。outputobjectモデルによって返されるデータ。

プロパティ

voice_idstring音声 ID。TTS API の voice パラメーターに指定します。gmt_createstring作成時刻。gmt_modifiedstring最終更新時刻。statusstring
CosyVoice のみが返します。
音声のステータス。有効な値については、「音声ステータスリファレンス」をご参照ください。target_modelstring音声を駆動する TTS モデル。voice_promptstring
CosyVoice 音声デザインのみが返します。
音声の説明テキスト。preview_textstring
CosyVoice 音声デザインのみが返します。
プレビューオーディオのテキスト。
usageobjectこのリクエストの使用量情報。

プロパティ

count integer常に 1。
{
    "output": {
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
        "gmt_create": "2025-12-10 14:54:09",
        "gmt_modified": "2025-12-10 17:47:48",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "target_model": "cosyvoice-v3.5-plus",
        "status": "OK",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary."
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

音声の削除

リクエストボディ

modelstring（必須）音声デザインモデル。有効な値は次のとおりです。
  • voice-enrollment： CosyVoice 音声デザイン。
inputobject（必須）入力パラメーターオブジェクト。

プロパティ

action string（必須）次の値に設定します： delete_voice。voice_id string（必須）
CosyVoice のみに適用されます。
削除する音声 ID。
以下の例では中国 (北京) リージョンの設定を使用します。{WorkspaceId} を実際のワークスペース ID に置き換えてください。
curl -X POST https://{WorkspaceId}.cn-beijing.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_idstringこのリクエストの一意な識別子。outputobjectモデルが返すデータ。空のオブジェクトです。usageobjectこのリクエストの使用量情報。

プロパティ

count integer常に 1。
{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

音声ステータスリファレンス

作成した音声は審査プロセスを経ます。以下のステータスは、model が voice-enrollment の場合の CosyVoice に適用されます。

ステータス

説明

DEPLOYING

レビュー中または処理中。

OK

レビュー合格。音声は使用可能な状態です。

UNDEPLOYED

レビュー不合格。音声は使用できません。