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

Key features

Compose lyrics and generate a complete song from a prompt
Generate a song from custom lyrics
Male and female vocal styles
Chinese and English lyrics and prompts
Streaming and non-streaming output modes
MP3 and WAV audio output formats

Supported model

Music generation model:

fun-music-preview
fun-music-v1

Supported languages:

Lyrics: Chinese, English
Prompts: Chinese, English

Quick start

Prerequisites

An API key. For more information, see Get an API key.
An API key set as an environment variable (recommended):
```
export DASHSCOPE_API_KEY="sk-xxx"
```

Important

At least one of lyrics and prompt is required. If both are provided, only lyrics takes effect and prompt is ignored.

Generate music from a prompt

Pass the prompt parameter to describe the desired music style and scene. The model automatically composes lyrics and generates a song.

curl

curl -X POST 'https://dashscope.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"
    }
}'

Python

import requests
import os
import json

api_key = os.getenv("DASHSCOPE_API_KEY")
url = "https://dashscope.aliyuncs.com/api/v1/services/audio/music/generation"

response = requests.post(url,
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "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"
        }
    }
)

result = response.json()
audio_url = result["output"]["audio"]["url"]
print(f"Music generated successfully! Download URL: {audio_url}")

Java

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

public class FunMusicDemo {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String endpoint = "https://dashscope.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.setDoOutput(true);

        String jsonBody = "{\"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\"}}";

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

        try (BufferedReader reader = new BufferedReader(
                new InputStreamReader(conn.getInputStream(), "UTF-8"))) {
            StringBuilder sb = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                sb.append(line);
            }
            System.out.println(sb.toString());
        }
    }
}

Generate music from lyrics

Pass the lyrics parameter with custom lyrics. The model sets the lyrics to music and performs the song.

curl

curl -X POST 'https://dashscope.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"
    }
}'

Python

import requests
import os
import json

api_key = os.getenv("DASHSCOPE_API_KEY")
url = "https://dashscope.aliyuncs.com/api/v1/services/audio/music/generation"

lyrics = """[verse]
Morning sunlight streams through the curtains,
The aroma of coffee fills the room.
Opening a book left unfinished yesterday,
Time quietly slips away like this.

[chorus]
Take it slow, no need to rush,
Life should be this easygoing.
Toss all the worries into the wind,
Embrace every sunny day and rainy season."""

response = requests.post(url,
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "model": "fun-music-v1",
        "input": {
            "lyrics": lyrics,
            "gender": "female"
        }
    }
)

result = response.json()
audio_url = result["output"]["audio"]["url"]
print(f"Music generated successfully! Download URL: {audio_url}")

Java

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

public class FunMusicLyricsDemo {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String endpoint = "https://dashscope.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.setDoOutput(true);

        String lyrics = "[verse]\\nMorning sunlight streams through the curtains,\\n"
            + "The aroma of coffee fills the room.\\n"
            + "Opening a book left unfinished yesterday,\\n"
            + "Time quietly slips away like this.\\n\\n"
            + "[chorus]\\nTake it slow, no need to rush,\\n"
            + "Life should be this easygoing.\\n"
            + "Toss all the worries into the wind,\\n"
            + "Embrace every sunny day and rainy season.";

        String jsonBody = "{\"model\":\"fun-music-v1\","
            + "\"input\":{\"lyrics\":\"" + lyrics + "\","
            + "\"gender\":\"female\"}}";

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

        try (BufferedReader reader = new BufferedReader(
                new InputStreamReader(conn.getInputStream(), "UTF-8"))) {
            StringBuilder sb = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                sb.append(line);
            }
            System.out.println(sb.toString());
        }
    }
}

Streaming

Streaming mode returns audio data incrementally as it's generated. Use it for real-time playback. To enable streaming, add the X-DashScope-SSE: enable Server-Sent Events (SSE) header to your request.

Note

Streaming and non-streaming modes have different character limits:

Non-streaming mode: lyrics supports 5 to 350 Chinese characters or 5 to 2,000 English characters. prompt supports 1 to 2,000 characters.
Streaming mode: lyrics supports 300 to 350 Chinese characters or 200 to 250 English words. prompt supports 5 to 1,000 Chinese characters or English words.

curl

curl -X POST 'https://dashscope.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 fitness and workout scenarios",
        "gender": "male"
    }
}'

Python

import requests
import os
import json
import base64

api_key = os.getenv("DASHSCOPE_API_KEY")
url = "https://dashscope.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 fitness and workout scenarios",
            "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}")

Java

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://dashscope.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 fitness and workout scenarios\","
            + "\"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);
                    }
                }
            }
        }
    }
}

Lyrics guidelines

When you provide your own lyrics, follow these guidelines to produce better results.

Structure tags

Lyrics include the following structure tags:

Tag	Description
`[intro]`	Intro — sets the mood
`[verse]`	Verse — tells the story
`[chorus]`	Chorus — emotional climax
`[bridge]`	Bridge — shifts perspective
`[outro]`	Outro — fades 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 face.
Borrowing half an eraser, fingertips spark like electric traces.
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 very end.

[chorus]
Youth is an unopened letter, filled with brave vows.
Even if the world flickers bright and dark, with you I see the light.
Love is like early summer rain, sweet even when it soaks the dream.
We run toward tomorrow with laughter, hand in hand, never looking back.

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

[chorus]
Youth is an unopened letter, filled with brave vows.
Even if the world flickers bright and dark, with you I see the light.
Love is like early summer rain, sweet even when it soaks the dream.
We run toward tomorrow with laughter, hand in hand, never looking back.

[outro]
The piano fades into the distance, starlight paves the long street.
The story is not over, the next page is still ablaze.

Content requirements

Originality: Don't copy published song lyrics or imitate the rhyme schemes and signature phrasing of well-known songs.
Content safety: Lyrics must not contain political, violent, pornographic, vulgar, horrific, or drug-related content. Keep the content wholesome and emotionally authentic.
Language: Only Chinese and English are supported.

Best practices

Write effective prompts

Describe the mood, scene, and instrument preferences in detail. The more specific the prompt, the closer the output matches your intent.

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

Prompt examples for different styles:

Style	Prompt example
Folk	A warm, soothing folk song with acoustic guitar, telling a story of lazy afternoons at a café
Chinese classical	A Chinese-style song with guzheng and bamboo flute, evoking ink-wash landscapes and tales of farewell
Rock	High-energy rock with distorted electric guitar and driving drums, singing about youthful rebellion and freedom
Ballad	A slow, emotional ballad with piano accompaniment, quiet and deep, expressing longing and bittersweet memories
Hip-hop	An upbeat hip-hop track with punchy 808 bass, full of street energy, rapping about city life
Children's song	A cheerful children's song with xylophone and hand drum, simple catchy rhythm, teaching kids about nature

Choose an audio format

mp3: Best for network transfer and storage. This is the default format.
wav: Best for post-processing and high-quality playback.

API reference

Music generation API reference

FAQ

What's the difference between lyrics and prompt?

The lyrics parameter accepts your own lyrics. The model strictly follows these lyrics to compose and perform the song. The prompt parameter accepts a natural-language description of the desired music style and scene. The model then writes the lyrics and generates the music automatically. At least one parameter is required. If both are provided, only lyrics takes effect.

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

Use non-streaming mode when you need only the final audio file — no incremental data is returned. Use streaming mode when you need to receive audio data incrementally during generation, for example, to play the audio while it's still being generated.

How long are the audio download URLs valid?

Audio download URLs expire after 24 hours. Download the file within this period. After the URL expires, call the API again to generate a new URL.

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

The character limits for lyrics and prompt differ between the two modes. In non-streaming mode, lyrics supports 5 to 350 Chinese characters or 5 to 2,000 English characters, and prompt supports 1 to 2,000 characters. In streaming mode, lyrics supports 300 to 350 Chinese characters or 200 to 250 English words, and prompt supports 5 to 1,000 Chinese characters or English words.