Fun-music model API reference - Alibaba Cloud Model Studio

Describes the API parameters of the Fun-music model for music generation.

User guide: For model introduction and selection suggestions, see Music generation.

Important

This model is currently in invitation-only preview. Apply for access through the Model Studio model gallery before use. The model is available only in the Chinese mainland deployment scope (Beijing region).

Prerequisites

An API key is required. For more information, see Get an API key.

Endpoint

POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer

Protocol: HTTPS. Streaming output supports SSE (Server-Sent Events).

Request headers

Parameter	Type	Required	Description
Authorization	string	Yes	`Bearer {api-key}`. Replace `{api-key}` with your API key.
Content-Type	string	Yes	`application/json`
X-DashScope-SSE	string	No	Set to `enable` to use SSE streaming output.

Request body

Non-streaming

curl -X POST 'https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "fun-music-v1",
    "input": {
        "prompt": "Fresh summer folk song, acoustic guitar and harmonica accompaniment, upbeat rhythm, suitable as background music for travel vlogs",
        "gender": "female"
    }
}'

Streaming

curl -X POST 'https://dashscope.aliyuncs.com/api/v1/services/audio/tts/SpeechSynthesizer' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-H "X-DashScope-SSE: enable" \
-d '{
    "model": "fun-music-v1",
    "input": {
        "prompt": "High-energy electronic dance music, synthesizer effects, full of energy, suitable for fitness and workout scenarios",
        "gender": "male"
    }
}'

model string (required)

Model name. Set to fun-music-v1.

input object (required)

Input parameters object.

Properties

lyrics string (conditionally required)

The lyrics content. Mutually exclusive with prompt. At least one is required.

Character limits:

Non-streaming mode: 5 to 350 characters for Chinese, 5 to 2,000 characters for English
Streaming mode: 300 to 350 Chinese characters, 200 to 250 English words

Note

If both lyrics and prompt are specified, only lyrics takes effect and prompt is ignored.

prompt string (conditionally required)

A text prompt. The model generates lyrics and music based on this prompt. Mutually exclusive with lyrics.

Character limits:

Non-streaming mode: 1 to 2,000 characters
Streaming mode: 5 to 1,000 Chinese characters or English words

gender string (optional) Default: female

The vocal gender. Valid values:

male: Male voice
female: Female voice

format string (optional) Default: mp3

The audio encoding format. Valid values:

mp3: Suitable for network transfer and storage
wav: Suitable for post-processing and high-quality playback

Response object

Non-streaming

{
    "output": {
        "audio": {
            "data": "",
            "expires_at": 1774936147,
            "id": "audio_46c51288-7ed6-95cc-a119-xxxxxxxxxxxx",
            "url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/fun-music/20260330/xxxxxxxx/a8db24cc-d35f-961b-af81-a9e8d8b01f67.mp3?xxx"
        },
        "extra_info": {
            "channels": 2,
            "lyrics": "[verse]\nMorning sunlight slips through the curtain,\nCoffee aroma fills up the room.\nOpen the book left unfinished yesterday,\nTime quietly drifts by this way.\n\n[chorus]\nTake it slow, there's no hurry,\nLife should be this carefree.\nToss your worries into the wind,\nEmbrace every sunny day and rainy season.",
            "sample_rate": 48000
        },
        "finish_reason": "stop"
    },
    "usage": {
        "duration": 200
    },
    "request_id": "46c51288-7ed6-95cc-a119-xxxxxxxxxxxx"
}

Streaming (intermediate message)

{
    "output": {
        "audio": {
            "data": "Base64-encoded audio data",
            "expires_at": 1774937185,
            "id": "audio_a8db24cc-d35f-961b-af81-xxxxxxxxxxxx"
        },
        "finish_reason": "null"
    },
    "request_id": "a8db24cc-d35f-961b-af81-xxxxxxxxxxxx"
}

Streaming (final message)

{
    "output": {
        "audio": {
            "expires_at": 1774937185,
            "id": "audio_a8db24cc-d35f-961b-af81-xxxxxxxxxxxx",
            "data": "",
            "url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/pre/fun-music/20260330/xxxxxxxx/a8db24cc-d35f-961b-af81-a9e8d8b01f67.mp3?xxx"
        },
        "extra_info": {
            "channels": 2,
            "sample_rate": "48000",
            "lyrics": "[verse]\nMorning sunlight slips through the curtain,\nCoffee aroma fills up the room.\nOpen the book left unfinished yesterday,\nTime quietly drifts by this way.\n\n[chorus]\nTake it slow, there's no hurry,\nLife should be this carefree.\nToss your worries into the wind,\nEmbrace every sunny day and rainy season."
        },
        "finish_reason": "stop"
    },
    "usage": {
        "duration": 200
    },
    "request_id": "a8db24cc-d35f-961b-af81-xxxxxxxxxxxx"
}

request_id string

The request ID, used for troubleshooting and tracing.

output object

The model output.

Properties

audio object

Audio data returned by the model.

Properties

data string

Base64-encoded audio data chunks in streaming mode. An empty string in non-streaming mode.

url string

The OSS URL of the full audio file, valid for 24 hours. Returned directly in non-streaming mode. In streaming mode, included only in the final message.

id string

The audio file ID.

expires_at integer

The Unix timestamp when the audio URL expires.

extra_info object

Additional information. Contains the following fields:

Properties

channels integer

The number of audio channels. For example, 2 indicates stereo.

sample_rate string

The audio sample rate. For example, "48000".

lyrics string

The lyrics content.

finish_reason string

Indicates whether generation is complete:

null: Generation is in progress
stop: Generation is complete

usage object

Billing information for this request.

Properties

duration integer

The music duration in seconds, used for billing.