给一句主题，自动写词、合成人声，产出一首完整曲子。 约 2-4 分钟，先看到歌词，再拿到 flac / wav / mp3 文件。
Give a theme; the service writes the lyrics, synthesises the vocals, and produces a finished song. Around 2-4 minutes — lyrics first, then the flac / wav / mp3.
实测 A800 80GB · 作词模型 + 音频生成模型
Measured on A800 80GB · lyricist + audio model
填好下面的参数，点击「生成歌曲」，等 2-4 分钟，flac / mp3 文件会自动出现在右侧。
Fill in the form and hit Generate; an flac/mp3 will appear in 2-4 minutes.
C major / B minor。小调 = 忧伤、大调 = 明亮。C major / B minor. Minor = sad, major = bright.flac/wav 无损（大）· mp3 有损但小 · wav32 32-bit 浮点，留给后期混音。flac/wav lossless (large) · mp3 lossy + small · wav32 float32 for mastering.提交一首歌的生成任务。请求立即返回 intent_id（< 1 s），之后用 /v1/song/status 轮询状态拿歌词和音频 URL。
Submit a song-generation job. Returns intent_id immediately (< 1 s); poll /v1/song/status to track lyrics + audio.
| 字段 | Field | 类型 | Type | 默认 | Default | 说明 | Description |
|---|---|---|---|---|---|---|---|
| theme | string | 必填required | 主题Theme | ||||
| language | string | "zh" | "zh" 或 "en" 等 ISO 639 代码ISO 639 code: "zh", "en", ... | ||||
| rhyme | string|null | null | 韵脚Rhyme suffix | ||||
| style | string|null | null | 风格描述Style hint | ||||
| vocal_gender | enum | "male" | male | female | any | ||||
| duration_hint | float | 220.0 | 期望时长（10-600 秒）Target duration (10-600 s) | ||||
| additional_instructions | string|null | null | 额外指令Extra instructions | ||||
| temperature | float | 0.85 | 采样温度Sampling temperature | ||||
| vocal_mode | enum | "sing" | sing / instrumental_from_lyrics / instrumental_quick | ||||
| track_classes | string[] | null | 主推乐器（drums/bass/guitar/...）Featured instruments (drums/bass/guitar/...) | ||||
| bpm | int|null | null | 手动覆盖 LM 给的 BPMOverride LM-suggested BPM | ||||
| key_scale | string|null | null | 手动覆盖调性Override key | ||||
| duration | float|null | null | 手动覆盖时长Override duration | ||||
| audio_format | string | "flac" | flac / wav / wav32 / mp3 | ||||
| inference_steps | int | 64 | DiT 推理步数DiT inference steps | ||||
| guidance_scale | float | 7.0 | CFG scale | ||||
| use_adg | bool | false | Adaptive Dynamic Guidance | ||||
| batch_size | int | 1 | 每次生成几首How many songs to generate | ||||
| generate_cover | bool | true | 是否同步生成封面图（与音频并行，不占本地显存）Generate album cover in parallel with audio (no local VRAM) | ||||
| cover_size | string|null | null | 封面比例 1:1 / 3:4 / 9:16 / 16:9 等，留空走部署默认Aspect: 1:1 / 3:4 / 9:16 / 16:9; null = deployment default |
{
"code": 200,
"data": {
"intent_id": "abc-...-uuid",
"status": "lyrics_pending",
"next_step": {
"method": "GET",
"url": "/v1/song/status?intent_id=abc-...",
"poll_interval_sec": 5
}
},
"error": null
}
轮询接口（建议每 5 秒一次）。每次返回当前状态、已就绪的歌词、最终的音频 URL。
Polling endpoint (recommended every 5 s). Returns current status, lyrics_meta once ready, and audio_url when complete.
| 字段 | Field | 类型 | Type | 要求 | Required | 说明 | Description |
|---|---|---|---|---|---|---|---|
| intent_id | string | 必填required | /v1/song/create 返回的 UUIDUUID returned by /v1/song/create |
| status | 含义 | Meaning |
|---|---|---|
| lyrics_pending | 作词模型正在写词（最长 ~150 s）Lyricist writing lyrics (~150 s) | |
| audio_pending | 歌词已就绪，音频任务已入队Lyrics done, audio queued | |
| audio_running | DiT 正在生成音频DiT generating audio | |
| completed | 完成 — audio.audio_url 可下载Done — audio.audio_url ready | |
| failed | 失败 — error 字段含原因Failed — see error field |
{
"intent_id": "abc-...-uuid",
"status": "completed",
"submitted_at": 1715170800.12,
"completed_at": 1715171064.55,
"lyrics_meta": { /* title / lyrics_zh / caption / bpm / key_scale / ... */ },
"audio": {
"store_status": "completed",
"file_paths": ["/path/to/song.flac"],
"audio_url": "/v1/audio?path=..."
},
"error": null
}
下载 status.audio.audio_url 指向的音频文件。返回二进制流，Content-Type 按格式而定。
Download the audio file at status.audio.audio_url. Returns a binary stream; Content-Type depends on format.
| 字段 | Field | 类型 | Type | 要求 | Required | 说明 | Description |
|---|---|---|---|---|---|---|---|
| path | string | 必填required | URL-encoded 音频路径（来自 status.audio.file_paths）URL-encoded audio path (from status.audio.file_paths) |
// 二进制音频流，Content-Type 例如 audio/flac、audio/wav、audio/mpeg。 // Binary audio stream — Content-Type is audio/flac, audio/wav, audio/mpeg, ...
POST /auth/login 拿 token。POST /auth/login first.ACESTEP_ENABLE_LYRICIST=true。ACESTEP_ENABLE_LYRICIST=true on the server.把下面这段经过实测的提示词复制给 Claude / Cursor / GPT，让它直接生成调用本接口的代码——包含异步轮询、错误处理、示例输入输出。
Paste the battle-tested prompt below into Claude, Cursor, or GPT and let it generate code that calls this API — covering async polling, error handling, and sample I/O.
已在主流编程 Agent 上跑过验证。涵盖 API 结构、认证、错误处理和示例输入/输出。粘贴后说一句 "用我的技术栈实现这个" 即可。
Tested on mainstream coding agents. Includes API shape, auth, error handling, and sample I/O. Paste it and say "build this in my stack".
POST /v1/song/create。POST /v1/song/create.