Copy

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.

Overview

Fun-Music is an end-to-end music generation model. Provide a natural language description or custom lyrics, and it returns a complete song:

prompt: Describe the music style, scene, mood, and instrument preferences. The model writes lyrics and generates a song automatically.
lyrics: Provide custom lyrics. The model composes and performs a song based on your lyrics.
gender: Select male or female vocals (fun-music-v1 only).
Streaming and non-streaming output
MP3 and WAV audio output

Differences between the two models

Fun-Music provides two models with the following differences:

Feature	fun-music-v1	fun-music-preview
prompt	Required (at least one of `prompt` or `lyrics`)	Required
lyrics	Optional if `prompt` is provided; if both are supplied, `lyrics` takes effect	Optional; if provided, `lyrics` takes priority
Vocal gender (gender)	Supported	Not supported

Audio output formats

Set the format parameter to specify the output format:

Format	Characteristics	Use cases
`mp3`	Lossy compression, small file size	Streaming, online playback, storage
`wav`	Lossless format, larger file size	Post-production, high-quality playback

Prerequisites

An API key. For more information, see Get an API key.
The API key configured as an environment variable (recommended):

export DASHSCOPE_API_KEY="sk-xxx"

Replace {WorkspaceId} in the sample code with your actual workspace ID. For more information, see Workspace management.

Quick start

The following examples demonstrate three typical use cases.

Generate a song from a prompt
Generate a song from lyrics

Pass the prompt parameter with a description of the music style and scene. The model writes the lyrics and composes the song.

curl

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

Pass the lyrics parameter with your lyrics. The model composes and generates a song based on them.

curl

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": {
        "lyrics": "[verse]\nMorning sunlight streams through the curtains,\nThe aroma of coffee fills the room.\nOpening a book left unfinished yesterday,\nTime quietly slips away like this.\n\n[chorus]\nTake it slow, no need to rush,\nLife should be this easygoing.\nToss all the worries into the wind,\nEmbrace every sunny day and rainy season.",
        "gender": "female"
    }
}'

Composition guide

Prompt

prompt is the primary parameter for describing your music creation intent. The model writes lyrics, arranges music, and generates a song based on your description. Writing tip: Use specific descriptions of mood, scene, and instrument preferences for better results.

Recommended: Melancholic piano, rainy night yearning
Not recommended: Melancholic music (too vague)

In your prompt, specify instruments (such as "piano accompaniment", "saxophone solo", or "guzheng and bamboo flute"), tempo (such as "upbeat", "slow", or "dense drum beats"), and emotional tone (such as "warm", "melancholic", "intense", or "laid-back"). The model follows these descriptions as closely as possible. More specific prompts produce more accurate results.

Prompt examples by style

Style	Prompt example
Folk	A warm, healing folk song with acoustic guitar, telling a story of a lazy afternoon in a cafe
Traditional Chinese	A traditional Chinese song with guzheng and bamboo flute, evoking misty landscapes and a farewell between wanderers
Rock	Intense rock with distorted electric guitar, dense drum beats, singing about youthful rebellion and freedom
Ballad	A slow ballad with piano accompaniment, quiet and deep, with a touch of melancholy, expressing longing and memories
Rap	A hip-hop rap with a sharp beat, 808 bass drums, full of street energy, telling stories of city life
Children's song	A cheerful children's song with xylophone and hand drums, simple and catchy rhythm, teaching kids about nature

Lyrics

The lyrics parameter accepts your lyrics. The model composes a song that follows them closely. Use song section tags to control the arrangement of song sections. Song section tags

Tag	Description
`[intro]`	Intro, sets the mood
`[verse]`	Verse, tells the story
`[chorus]`	Chorus, emotional climax
`[bridge]`	Bridge, shifts perspective
`[outro]`	Outro, gradual fade-out

Lyrics example

[intro]
Piano keys fall gently, the evening breeze is cool.
That summer, heartbeats quietly grew warm.

[verse]
By the classroom window, sunlight slants across your profile.
Borrowing half an eraser, fingertips spark an electric line.
On the way home from school, bicycle bells chase the clouds.
You said the future is far away, but I wanted to walk to the end.

[chorus]
Youth is an unopened letter, filled with brave promises.
Even if the world flickers bright and dark, with you I see the light.
Love is like the sweet rain of early summer, soaking dreams without fear of distance.
We run toward tomorrow with laughter, hand in hand, never looking back.

[bridge]
Later, wind and rain scattered the paper umbrella, silence replaced the answers.
But the song in my heart is unfinished, still waiting for "don't drift apart."

[chorus]
Youth is an unopened letter, filled with brave promises.
Even if the world flickers bright and dark, with you I see the light.
Love is like the sweet rain of early summer, soaking dreams without fear of distance.
We run toward tomorrow with laughter, hand in hand, never looking back.

[outro]
The piano fades, starlight paves the long street.
The story is unfinished, the next page is still passionate.

Writing requirements

Originality: Don't copy or imitate lyrics, rhyme schemes, or signature phrases from published songs.
Content safety: Don't include content related to politics, violence, pornography, vulgarity, horror, or drugs. Keep the content positive and emotionally genuine.
Language: Only Chinese and English lyrics are supported. Japanese, Korean, and other languages aren't supported.

Vocal gender (gender)

The gender parameter selects the vocal gender. Only supported by the fun-music-v1 model. The default is female.

female: Female vocals (default)
male: Male vocals

Advanced features

Streaming output

Streaming mode returns audio data progressively as it's generated, which is ideal for real-time playback. Both fun-music-v1 and fun-music-preview support this mode. To enable streaming output, add X-DashScope-SSE: enable to the request header.

Streaming and non-streaming modes have different character limits:

Non-streaming mode: lyrics accepts 5-350 Chinese characters or 5-2,000 English characters; prompt accepts 1-2,000 characters.
Streaming mode: lyrics accepts 300-350 Chinese characters or 200-250 English words; prompt accepts 5-1,000 characters (Chinese or English).

curl

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

Supported models and regions

China (Beijing)

To call the following models, use an API key from the Beijing region:

fun-music-v1
fun-music-preview

API reference

Music generation API reference

FAQ

Can I specify instruments, tempo, or mood?

Yes. Describe them directly in your prompt, such as "piano accompaniment, slow tempo, melancholic." The model follows these descriptions as closely as possible. More specific prompts produce more accurate results. For detailed prompt writing tips, see Prompt.

Which model should I choose?

fun-music-v1 supports vocal gender selection and generates higher quality audio. fun-music-preview supports custom lyrics and prompt-based generation. For a detailed comparison, see Differences between the two models.

How long are audio download URLs valid?

Audio file download URLs are valid for 24 hours. Download the files within this period. After the URL expires, call the API again to generate a new one.

What's the difference between lyrics and prompt?

The lyrics parameter takes your lyrics, and the model composes a song based on them. The prompt parameter takes a natural language description of the music style and scene, and the model writes lyrics and generates music automatically. Parameter requirements differ by model: for fun-music-v1, at least one of the two parameters is required; if both are provided, lyrics takes effect. For fun-music-preview, prompt is required; lyrics is optional and takes priority over prompt when provided.

When should I use streaming vs. non-streaming mode?

Use non-streaming mode if you only need the final audio file. The API call is simpler. Use streaming mode if you need audio data delivered progressively during generation, such as for real-time playback.

What are the parameter limits for streaming vs. non-streaming mode?

Character limits for lyrics and prompt differ between the two modes. In non-streaming mode, lyrics accepts 5-350 Chinese characters or 5-2,000 English characters, and prompt accepts 1-2,000 characters. In streaming mode, lyrics accepts 300-350 Chinese characters or 200-250 English words, and prompt accepts 5-1,000 characters (Chinese or English).

​Overview

​Differences between the two models

​Audio output formats

​Prerequisites

​Quick start

​Composition guide

​Prompt

​Lyrics

​Vocal gender (gender)

​Advanced features

​Streaming output

​Supported models and regions

​API reference

​FAQ

​Can I specify instruments, tempo, or mood?

​Which model should I choose?

​How long are audio download URLs valid?

​What's the difference between lyrics and prompt?

​When should I use streaming vs. non-streaming mode?

​What are the parameter limits for streaming vs. non-streaming mode?

Overview

Differences between the two models

Audio output formats

Prerequisites

Quick start

Composition guide

Prompt

Lyrics

Vocal gender (gender)

Advanced features

Streaming output

Supported models and regions

API reference

FAQ

Can I specify instruments, tempo, or mood?

Which model should I choose?

How long are audio download URLs valid?

What's the difference between lyrics and prompt?

When should I use streaming vs. non-streaming mode?

What are the parameter limits for streaming vs. non-streaming mode?