Alibaba Cloud Model Studio:音声生成APIリファレンス

HTTPS経由でテキストプロンプトと参照音声を送信し、生成された音声ファイルを受信します。このページでは、リクエスト、レスポンス、およびエラー処理について説明します。

前提条件

APIキーとワークスペースIDを取得してください。これらをDASHSCOPE_API_KEYおよびSFM_WORKSPACE_ID環境変数として設定してください。

以下のエンドポイントにHTTPS POSTリクエストを送信してください。{WorkspaceId}をお使いのワークスペースIDに置き換えてください。

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

ヘッダー

ヘッダー	必須	説明
Authorization	はい	Bearer <API Key>
Content-Type	はい	application/json

リクエスト例

curl --request POST \
  "https://$SFM_WORKSPACE_ID.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer" \
  --max-time 300 \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen-audio-3.1-tts-next",
    "input": {
      "text_prompt": "A woman clearly says: Hello, welcome.",
      "format": "wav",
      "sample_rate": 48000,
      "channels": 2
    }
  }'

例示用のIDとプレースホルダーのダウンロードURLを含むレスポンス例：

{
  "request_id": "example-request-id",
  "output": {
    "finish_reason": "stop",
    "audio": {
      "data": "",
      "url": "https://example.com/generated.wav",
      "id": "audio_example-request-id",
      "expires_at": 1789616932,
      "duration": 1.12
    }
  },
  "usage": {
    "duration": 1
  }
}

実際のレスポンスのoutput.audio.urlを使用してファイルをダウンロードしてください。URLの有効期間は24時間です。上記のプレースホルダーURLを使用して音声をダウンロードしないでください。

リクエストパラメーター

modelはトップレベルのフィールドです。すべての生成パラメーターはinputオブジェクトに属します。

フィールド	型	必須	デフォルト	説明
model	string	はい	—	モデルID。「サポートされているモデル」を参照してください。
input	object	はい	—	音声生成の入力。
input.text_prompt	string	はい	—	音声の説明または合成するテキスト。@voice1、@voice2、@voice3を使用して、音声クリップを順番に参照してください。長さの上限はモデル表に記載されています。
input.references	array	いいえ	—	参照音声クリップ。テキストのみの生成の場合は省略してください。現在のモデルは最大3件のクリップを受け付けます。各クリップの長さは30秒以内、サイズは10 MB以内です。
input.references[].audio_url	string	条件付き	—	サービスからアクセス可能な公開音声URL。このフィールドまたはaudio_dataのいずれかを指定してください。両方は指定できません。
input.references[].audio_data	string	条件付き	—	音声データURI：data:{mime_type};base64,{base64_encoded_data}。audio_urlとは相互に排他的です。
input.format	string	いいえ	wav	出力形式：wav、mp3、またはpcm。Opus出力はサポートされていません。
input.sample_rate	integer	いいえ	48000	出力サンプリングレート（Hz）：8000、16000、24000、44100、または48000。
input.channels	integer	いいえ	2	チャンネル数：1（モノラル）または2（ステレオ）。
input.volume	integer	いいえ	50	音量。範囲：[0, 100]。
input.enable_cbr	boolean	いいえ	false	MP3専用。trueは固定ビットレート（CBR）を有効にし、falseは可変ビットレート（VBR）を使用します。
input.bit_rate	integer	いいえ	128	MP3 CBR専用（kbps単位）。実際の出力はサンプリングレートとサポートされているMP3ビットレートレベルによって異なります。以下を参照してください。
input.quality	integer	いいえ	5	MP3 VBR専用。範囲：[0, 9]。0が最高品質です。
input.rate	float	いいえ	1.0	話速。範囲：[0.5, 2.0]。
input.seed	integer	いいえ	42	リクエストレベルのランダムシード。
input.enable_aigc_tag	boolean	いいえ	false	生成された音声にAIGC識別ウォーターマークを追加するかどうか。

参照音声はWAV、MP3、OGG Opusをサポートしていますが、生のPCMはサポートしていません。参照形式と出力形式には異なる制限があります。OGG Opusは入力として使用できますが、Opusは出力として使用できません。

参照音声は、システムまたはクローン化された音声IDではなく、URLまたはBase64データを通じて送信してください。

MP3 CBRビットレート

サンプリングレート（Hz）	最小出力ビットレート（kbps）	最大出力ビットレート（kbps）
8000	8	64
16000, 24000	8	160
44100, 48000	32	320

サンプリングレートとMP3ビットレートレベルによって出力ビットレートが決まります。表に示されているのは出力の範囲であり、各範囲内のすべての整数値がサポートされているわけではありません。範囲外の値は対応する境界値に制限されます。

参照音声の送信

このPythonの例では、二つの参照オーディオクリップを使用して二人の話者による会話を生成します。requestsをインストールし、それぞれ異なる話者を含みモデルの制限を満たすreference1.wavおよびreference2.wavを用意して、前述の環境変数を設定してください。

スロットはreferencesリストの順序に従います。最初の項目であるreference1.wavは@voice1に対応し、二番目の項目であるreference2.wavは@voice2に対応します。この例では、各クリップをBase64エンコードし、プロンプト内で両方の話者を参照しています。

import base64
import os
from pathlib import Path

import requests

reference1 = base64.b64encode(Path("reference1.wav").read_bytes()).decode("ascii")
reference2 = base64.b64encode(Path("reference2.wav").read_bytes()).decode("ascii")
workspace_id = os.environ["SFM_WORKSPACE_ID"]
endpoint = (
    f"https://{workspace_id}.cn-beijing.maas.aliyuncs.com"
    "/api/v1/services/audio/tts/SpeechSynthesizer"
)
response = requests.post(
    endpoint,
    headers={
        "Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-audio-3.1-tts-next",
        "input": {
            "text_prompt": "@voice1 says: It is sunny today. Shall we take a walk? @voice2 replies: Sure, let us go to the park.",
            "references": [
                {"audio_data": f"data:audio/wav;base64,{reference1}"},
                {"audio_data": f"data:audio/wav;base64,{reference2}"}
            ],
            "format": "wav",
        },
    },
    timeout=300,
)
response.raise_for_status()
result = response.json()
audio_response = requests.get(result["output"]["audio"]["url"], timeout=60)
audio_response.raise_for_status()
Path("output.wav").write_bytes(audio_response.content)

URLを使用するには、リスト項目を{"audio_url": "publicly accessible audio URL"}に置き換え、audio_dataを省略してください。参照番号はリストの順序に従い、既存の項目を指す必要があります。

レスポンスパラメーター

フィールド	型	説明
request_id	string	トラブルシューティング用のリクエストID。
output.finish_reason	string	正常完了時は「stop」。
output.audio.data	string	このリクエストモードでは空の文字列になります。完全な音声はoutput.audio.urlからダウンロードしてください。
output.audio.url	string	完全な音声のダウンロードURL。有効期間は24時間です。
output.audio.id	string	生成された音声のID。
output.audio.expires_at	integer	ダウンロードURLの有効期限タイムスタンプ。
output.audio.duration	float	生成された音声の長さ（秒）。
usage.duration	integer	生成された音声の長さを最も近い整数秒に丸めた値。このフィールドはトークン料金の計算には使用されません。

ポッドキャストのリクエストでは最大240秒（4分）の音声を生成できます。その他のシナリオではリクエストごとに120秒に制限されます。料金については、モデルの料金を参照してください。

サポートされているモデル

モデルID	プロンプトの上限	リクエストごとの最大生成時間
qwen-audio-3.1-tts-next	3,000文字	ポッドキャスト：240秒（4分）、その他のシナリオ：120秒

ユースケース、音声サンプル、プロンプトのガイダンスについては、音声生成を参照してください。このドキュメントの例ではこのモデルを使用しています。

エラー処理

エラーレスポンスの例：

{
  "request_id": "example-request-id",
  "code": "CLIENT_ERROR",
  "message": "text_prompt exceeds the maximum length of 3000 characters."
}

HTTPステータス	code	アクション
400	CLIENT_ERROR	プロンプトの長さ、参照の数と長さ、URL/Base64の排他性、参照インデックス、およびサポートされていないvoiceフィールドの使用を確認してください。
404	InvalidParameter	「Model not exist.」が表示される場合は、モデルID、リージョン、およびアカウントでのモデルの利用可否を確認してください。
401	InvalidApiKey	APIキーの有効性を確認してください。
403	AccessDenied	モデルへのアクセス権限を確認してください。
429	Throttling.RateQuota	リクエストレートを下げて再試行してください。
400	DataInspectionFailed	プロンプトまたは参照音声がコンテンツ安全要件を満たしているか確認してください。
500	InternalError	request_idを保持して後で再試行するか、テクニカルサポートにお問い合わせください。