Music generation

Differences between the two models

Fun-Music provides two models with the following differences:

Audio output formats

Set the format parameter to specify the output format:

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)

Prompt examples by style

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

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

Instrumental mode (is_instrumental)

Set is_instrumental to true to generate instrumental music (no vocals). When is_instrumental is set to true, lyrics and gender are ignored. The default value is false.

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.

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

import requests
import os
import json
import base64

api_key = os.getenv("DASHSCOPE_API_KEY")
url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/music/generation"

response = requests.post(url,
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "X-DashScope-SSE": "enable"
    },
    json={
        "model": "fun-music-v1",
        "input": {
            "prompt": "High-energy electronic dance music, synthesizer effects, full of energy, suitable for workout scenes",
            "gender": "male"
        }
    },
    stream=True
)

output_file = "output.mp3"
with open(output_file, "wb") as f:
    for line in response.iter_lines():
        if not line:
            continue
        decoded = line.decode("utf-8")
        if decoded.startswith("data:"):
            data = json.loads(decoded[5:])
            finish_reason = data.get("output", {}).get("finish_reason")
            if finish_reason == "null":
                audio_data = data["output"]["audio"].get("data", "")
                if audio_data:
                    f.write(base64.b64decode(audio_data))
            elif finish_reason == "stop":
                print(f"Music generation complete! Saved to {output_file}")

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class FunMusicStreamDemo {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String endpoint = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/music/generation";

        HttpURLConnection conn = (HttpURLConnection) new URL(endpoint).openConnection();
        conn.setRequestMethod("POST");
        conn.setRequestProperty("Authorization", "Bearer " + apiKey);
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setRequestProperty("X-DashScope-SSE", "enable");
        conn.setDoOutput(true);

        String jsonBody = "{\"model\":\"fun-music-v1\","
            + "\"input\":{\"prompt\":\"High-energy electronic dance music, synthesizer effects, full of energy, suitable for workout scenes\","
            + "\"gender\":\"male\"}}";

        try (OutputStream os = conn.getOutputStream()) {
            os.write(jsonBody.getBytes("UTF-8"));
        }

        String outputFile = "output.mp3";
        try (BufferedReader reader = new BufferedReader(
                new InputStreamReader(conn.getInputStream(), "UTF-8"));
             FileOutputStream fos = new FileOutputStream(outputFile)) {
            String line;
            while ((line = reader.readLine()) != null) {
                if (line.startsWith("data:")) {
                    String data = line.substring(5);
                    if (data.contains("\"finish_reason\":\"null\"")) {
                        int start = data.indexOf("\"data\":\"") + 8;
                        int end = data.indexOf("\"", start);
                        if (start > 8 && end > start) {
                            byte[] chunk = Base64.getDecoder().decode(
                                data.substring(start, end));
                            fos.write(chunk);
                        }
                    } else if (data.contains("\"finish_reason\":\"stop\"")) {
                        System.out.println("Music generation complete! Saved to " + outputFile);
                    }
                }
            }
        }
    }
}

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).