Fun-Music model API reference-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

API parameters for the Fun-Music music generation model.

User guide: For model overview and selection guidance, see Music generation.

Important

This model is currently in limited preview. Apply for access on the Model Gallery before use. This model is available only in the China (Beijing) region.

Prerequisites

An API key is required. To get one, see Get an API key.

Endpoint

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/music/generation, Replace WorkspaceId with your actual workspace ID.

Protocol: HTTPS. For streaming output, set the X-DashScope-SSE request header to enable SSE (Server-Sent Events).

Important

Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

China (Beijing): from https://dashscope.aliyuncs.com to https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: from https://dashscope-intl.aliyuncs.com to https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Model Studio console. The existing domain remains fully functional.

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 enable SSE streaming output.

Request body

Non-streaming

curl -X POST 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/music/generation' \
-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 tempo, suitable as background music for travel vlogs",
        "gender": "female"
    }
}'

Streaming

curl -X POST 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/music/generation' \
-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 workout scenes",
        "gender": "male"
    }
}'

model string (required)

Model name. Allowed values:

fun-music-v1
fun-music-preview

input object (required)

Input parameters.

Properties

prompt string (conditionally required)

A text prompt. The model automatically composes and generates music based on this prompt.

fun-music-v1: Either lyrics or prompt must be provided.
fun-music-preview: Required.

Character limits:

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

Note

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

lyrics string (conditionally required)

Lyrics for the generated song.

fun-music-v1: Either prompt or lyrics must be provided.
fun-music-preview: Optional.

Character limits:

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

Note

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

is_instrumental boolean (optional) Default: false

Specifies whether to generate instrumental music. Set to true to generate instrumental music (no vocals), or false to generate a song with vocals.

Note

When is_instrumental is set to true, the lyrics and gender parameters are ignored.

gender string (optional) Default: female

Vocal gender. Only supported by the fun-music-v1 model. Valid values:

male: Male voice
female: Female voice

format string (optional) Default: mp3

Audio encoding format. Valid values:

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

enable_aigc_watermark boolean (optional) Default: false

AIGC watermark switch. When enabled, a Morse code audio signal representing "AI" (·— ··) is appended to the end of the generated audio to identify the content as AI-generated. Enabling the watermark increases the audio duration.

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

Request ID, used for troubleshooting and log tracing.

output object

Model output.

Properties

audio object

Audio output from the model.

Properties

data string

Base64-encoded audio chunks in streaming mode. Empty string in non-streaming mode.

url string

OSS URL of the complete audio file, valid for 24 hours. Present in all non-streaming responses and in the final streaming message only.

id string

Audio file ID.

expires_at integer

Unix timestamp indicating when the audio URL expires.

extra_info object

Additional metadata about the generated audio.

Properties

channels integer

Number of audio channels. For example, 2 indicates stereo.

sample_rate string

Audio sample rate. For example, "48000".

lyrics string

Lyrics of the generated song.

finish_reason string

Generation status:

null: Generation is in progress
stop: Generation is complete

usage object

Billing information for this request.

Properties

duration integer

Music duration in seconds, used for billing.