Alibaba Cloud Model Studio:Audio generation API reference

Submit text prompts and reference audio over HTTPS to receive generated audio files. This page describes requests, responses, and error handling.

Prerequisites

Obtain an API key and workspace ID. Set them as the DASHSCOPE_API_KEY and SFM_WORKSPACE_ID environment variables.

Send HTTPS POST requests to the following endpoint. Replace {WorkspaceId} with your workspace ID.

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

Headers

Header	Required	Description
Authorization	Yes	Bearer <API Key>
Content-Type	Yes	application/json

Request example

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
    }
  }'

Example response, with illustrative IDs and a placeholder download 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
  }
}

Download the file using output.audio.url from the actual response. The URL is valid for 24 hours. Do not use the placeholder URL above to download audio.

Request parameters

model is a top-level field. All generation parameters belong in the input object.

Field	Type	Required	Default	Description
model	string	Yes	—	Model ID. See Supported models.
input	object	Yes	—	Audio generation input.
input.text_prompt	string	Yes	—	Audio description or text to synthesize. Use @voice1, @voice2, and @voice3 to reference audio clips in order. Length limits are listed in the model table.
input.references	array	No	—	Reference audio clips. Omit for text-only generation. The current model accepts up to 3 clips, each no longer than 30 seconds and no larger than 10 MB.
input.references[].audio_url	string	Conditional	—	Public audio URL accessible to the service. Provide either this field or audio_data, not both.
input.references[].audio_data	string	Conditional	—	Audio data URI: data:{mime_type};base64,{base64_encoded_data}. Mutually exclusive with audio_url.
input.format	string	No	wav	Output format: wav, mp3, or pcm. Opus output is not supported.
input.sample_rate	integer	No	48000	Output sample rate in Hz: 8000, 16000, 24000, 44100, or 48000.
input.channels	integer	No	2	Channel count: 1 (mono) or 2 (stereo).
input.volume	integer	No	50	Volume. Range: [0, 100].
input.enable_cbr	boolean	No	false	MP3 only. true enables constant bitrate (CBR); false uses variable bitrate (VBR).
input.bit_rate	integer	No	128	MP3 CBR only, in kbps. Actual output depends on the sample rate and supported MP3 bitrate levels. See below.
input.quality	integer	No	5	MP3 VBR only. Range: [0, 9], where 0 is the highest quality.
input.rate	float	No	1.0	Speech rate. Range: [0.5, 2.0].
input.seed	integer	No	42	Request-level random seed.
input.enable_aigc_tag	boolean	No	false	Whether to add an AIGC identification watermark to the generated audio.

Reference audio supports WAV, MP3, and OGG Opus, but not raw PCM. Reference and output formats have different limits: OGG Opus can be used as input, but Opus cannot be used as output.

Submit reference audio through a URL or Base64 data, not through a system or cloned voice ID.

MP3 CBR bitrate

Sample rate (Hz)	Minimum output bitrate (kbps)	Maximum output bitrate (kbps)
8000	8	64
16000, 24000	8	160
44100, 48000	32	320

The sample rate and MP3 bitrate levels determine the output bitrate. The table lists output bounds, not support for every integer in each range. Values outside the range are constrained to the corresponding bounds.

Submit reference audio

This Python example uses two reference audio clips to generate a two-speaker conversation. Install requests, prepare reference1.wav and reference2.wav, each containing a different speaker and meeting the model limits, and set the environment variables described above.

Slots follow the order of the references list: the first item, reference1.wav, corresponds to @voice1; the second item, reference2.wav, corresponds to @voice2. The example Base64-encodes each clip and references both speakers in the prompt.

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)

To use a URL, replace the list item with {"audio_url": "publicly accessible audio URL"} and omit audio_data. Reference numbers follow the list order and must point to existing items.

Response parameters

Field	Type	Description
request_id	string	Request ID for troubleshooting.
output.finish_reason	string	"stop" at normal completion.
output.audio.data	string	An empty string for this request mode. Download the complete audio from output.audio.url.
output.audio.url	string	Complete audio download URL, valid for 24 hours.
output.audio.id	string	Generated audio ID.
output.audio.expires_at	integer	Download URL expiration timestamp.
output.audio.duration	float	Generated audio duration in seconds.
usage.duration	integer	Generated audio duration rounded to the nearest whole second. This field is not used to calculate token charges.

Podcast requests can generate up to 240 seconds (4 minutes) of audio; other scenarios are limited to 120 seconds per request. For prices, see Model pricing.

Supported models

Model ID	Prompt limit	Maximum generated duration per request
qwen-audio-3.1-tts-next	3,000 characters	Podcasts: 240 seconds (4 minutes); other scenarios: 120 seconds

For use cases, audio examples, and prompt guidance, see Audio generation. The examples in this document use this model.

Error handling

Example error response:

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

HTTP status	code	Action
400	CLIENT_ERROR	Check prompt length, reference count and duration, URL/Base64 exclusivity, reference indices, and use of the unsupported voice field.
404	InvalidParameter	For "Model not exist.", check the model ID, region, and model availability for your account.
401	InvalidApiKey	Check API key validity.
403	AccessDenied	Check model access permissions.
429	Throttling.RateQuota	Reduce the request rate.
400	DataInspectionFailed	Check whether the prompt or reference audio meets content safety requirements.
500	InternalError	Retain the request_id and retry later or contact technical support.