音乐生成 - StepFun 开放平台文档中心

文本生成音乐接口采用异步的“提交 + 查询”模式：先创建生成任务并获取 task_id，再轮询任务状态，直到任务进入 SUCCESS 或 FAILED 终态。

音乐生成是自回归长任务，生成一首完整歌曲通常需要数十秒到数分钟。

服务地址

POST https://api.stepfun.com/v1/audio/music

能力范围

本次提供三个任务类型，覆盖四种用法：

用法	`task`	输入	输出
歌曲生成	`text_to_music`	风格描述 + 可选歌词	带人声的完整歌曲
纯器乐生成	`text_to_music` + `instrumental=true`	风格描述	无人声器乐
歌曲翻唱 / 风格切换	`music_cover`	参考歌曲 + 风格描述 + 歌词	跟随原曲旋律的翻唱
干声配乐	`vocal_to_music`	无伴奏干声 + 风格描述 + 歌词	保留输入音色的完整歌曲

text_to_music 未提供 lyrics 时，服务端会自动生成歌词。

通用约定

请求头

Header	必填	说明
`Authorization`	是	`Bearer $STEP_API_KEY`
`Content-Type`	是	`application/json; charset=utf-8`

统一错误响应

所有非 2xx 响应采用以下结构：

{
  "error": {
    "message": "错误描述",
    "type": "错误类型标识"
  }
}

客户端应根据 error.type 做程序化判断，不要匹配 message 文本。响应同时返回 x-should-retry 头：

参数、鉴权和资源类错误（400 / 401 / 404）：false
速率限制和临时服务故障（429 / 500 / 503）：true
额度类 429 重试无效，仍需根据 error.type 单独处理。

音频输入字段使用原始文件字节的 Base64 字符串，不包含 data: 前缀。

提交音乐生成任务

POST https://api.stepfun.com/v1/audio/music/submit

请求参数

task string required
任务类型，支持 text_to_music、music_cover 和 vocal_to_music。
model_id string required
音乐模型标识，固定填 stepaudio-3-music-preview。
caption string required
曲风、人声、情绪、调式等风格描述。
lyrics string optional
歌词，支持歌曲结构标签。music_cover 和 vocal_to_music 必填；text_to_music 不传时由服务端自动写词。
instrumental boolean optional
是否生成纯器乐，默认 false，仅 text_to_music 支持。
song_audio string optional
完整参考歌曲的 Base64 编码，music_cover 必填。
vocal_audio string optional
无伴奏干声的 Base64 编码，vocal_to_music 必填。
response_format string optional
输出格式，支持 wav、flac、opus、mp3 和 pcm，默认 wav。
sample_rate integer optional
输出采样率，默认 48000；省略或传 0 时保持模型原生采样率。
bit_rate integer optional
MP3 / Opus 比特率，单位为 kbps。
lyrics_rewrite boolean optional
是否改写传入的歌词，默认 false。
disable_caption_rewrite boolean optional
是否跳过 caption 自动改写，默认 false。
max_tokens integer optional
生成 token 数上限，默认 16000。
temperature number optional
采样温度，默认 0.85，暂不支持 0。
top_k integer optional
采样参数，默认 80。
top_p number optional
采样参数，默认 0.92。
repetition_penalty number optional
重复惩罚，默认 1.08。

参数适用矩阵

参数	`text_to_music` 歌曲	`text_to_music` 器乐	`music_cover`	`vocal_to_music`
`caption`	必填	必填	必填	必填
`lyrics`	可选，留空自动写词	禁止传	必填	必填
`instrumental`	省略或 `false`	必须为 `true`	不支持	不支持
`song_audio`	不使用	不使用	必填	不使用
`vocal_audio`	不使用	不使用	不使用	必填

参数说明

器乐与歌词

instrumental=true 时不得同时传入 lyrics。歌词中的 [Instrumental] 仅表示局部器乐段，不能代替顶层的 instrumental=true。

翻唱

music_cover 的旋律跟随参考歌曲，caption 控制风格、音色、编曲和情绪。建议传入与原曲演唱内容一致的歌词。

干声配乐

vocal_to_music 的旋律主要跟随干声，并保留输入干声的人声音色。干声实际演唱内容需要是 lyrics 的子集或全集。

Caption 改写

服务端默认将 caption 改写为规范的英文 style prompt，并通过查询接口的 rewritten_caption 返回。 disable_caption_rewrite=true 不能与 lyrics_rewrite=true 同时使用；在非器乐 text_to_music 场景使用时，必须显式提供歌词。

输出时长

输出时长由模型决定，无法通过参数精确控制。同一输入多次生成的时长可能不同，通常为 1～3 分钟。

歌词结构标签

歌词结构标签需要独占一行。常用标签：

[Intro]
[Verse 1]
[Pre-Chorus]
[Chorus 1]
[Bridge]
[Instrumental]
[Hook]
[Break]
[Drop]
[Ad-lib]
[Outro]

[Verse 1]
青椒还沾着晨露
你挑的番茄滚到脚边

[Instrumental]

[Chorus 1]
初秋的菜场挤着人潮
你背影越走越渺小

Caption 写法建议

caption 支持中文或英文，建议描述以下维度：

维度	示例
曲风	lo-fi、R&B、city pop、dance-pop
人声	女声、男声、温暖、气声、颤音
律动	缓慢、中速、轻快、适合跳舞
音色质感	温暖、开阔、颗粒感、朦胧
情绪	怀旧、惆怅、振奋、有希望
调式	B 小调、D 小调、C 大调

响应

{
  "task_id": "01959f5e-0f31-7a2b-9c4d-1234567890ab"
}

task_id 用于查询任务结果和问题排查。

错误码

HTTP	`error.type`	触发条件
400	`request_params_invalid`	JSON 非法、缺少必填字段、参数值或参数组合错误
401	`not_allowed`	鉴权令牌缺失或无效
402	`insufficient_credit`	Credit 余额不足
404	`model_invalid`	模型 ID 错误或账号没有模型权限
429	`rate_limited`	请求速率或并发超过限制
429	`project_credit_limit_exceeded` / `member_project_credit_limit_exceeded`	项目或成员达到 Credit 上限
503	`service_unavailable`	服务负载过高或任务入队失败

内容审核可能在提交阶段同步返回 451，也可能在任务执行阶段以 FAILED + error.stage=censor 返回。

调用示例

歌曲生成
纯器乐
歌曲翻唱
干声配乐

curl -X POST "https://api.stepfun.com/v1/audio/music/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task": "text_to_music",
    "model_id": "stepaudio-3-music-preview",
    "caption": "A soul and R&B song, female vocal, D minor, warm and nocturnal",
    "lyrics": "[Verse 1]\n...\n[Chorus 1]\n...",
    "response_format": "mp3"
  }'

curl -X POST "https://api.stepfun.com/v1/audio/music/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task": "text_to_music",
    "model_id": "stepaudio-3-music-preview",
    "instrumental": true,
    "caption": "流行风格古筝曲，穿插长笛和萧声，温暖辽阔",
    "response_format": "mp3"
  }'

curl -X POST "https://api.stepfun.com/v1/audio/music/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task": "music_cover",
    "model_id": "stepaudio-3-music-preview",
    "caption": "Soul and R&B with funk influences, warm and breathy vocal",
    "lyrics": "[Verse 1]\n...",
    "song_audio": "<base64 of reference song>",
    "response_format": "mp3"
  }'

curl -X POST "https://api.stepfun.com/v1/audio/music/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task": "vocal_to_music",
    "model_id": "stepaudio-3-music-preview",
    "caption": "Vibrant dance-pop with uplifting R&B influences",
    "lyrics": "[Verse 1]\n...",
    "vocal_audio": "<base64 of dry vocal>",
    "response_format": "mp3"
  }'

查询任务结果

POST https://api.stepfun.com/v1/audio/music/query 建议每 5 秒轮询一次，直到 status 进入终态；成功后请及时保存音频。

请求参数

{
  "task_id": "01959f5e-0f31-7a2b-9c4d-1234567890ab"
}

参数	类型	必填	说明
`task_id`	string	是	提交接口返回的任务 ID

任务状态

状态	说明
`PENDING`	任务已入队
`RUNNING`	任务正在处理
`SUCCESS`	生成完成，可以获取音频
`FAILED`	生成失败，不会回退

进行中响应

{
  "status": "RUNNING",
  "task": "text_to_music",
  "caption": "A soul and R&B song, female vocal, D minor",
  "lyrics": "[Verse 1]\n...",
  "response_format": "mp3",
  "sample_rate": 48000
}

成功响应

{
  "status": "SUCCESS",
  "task": "text_to_music",
  "caption": "A soul and R&B song, female vocal, D minor",
  "lyrics": "[Verse 1]\n...",
  "response_format": "mp3",
  "sample_rate": 48000,
  "audio": "<base64-encoded generated audio>",
  "rewritten_caption": "A soul and R&B song, female vocal, D minor, warm and nocturnal",
  "rewritten_lyrics": "[Verse 1]\n...\n[Chorus 1]\n..."
}

失败响应

{
  "status": "FAILED",
  "task": "music_cover",
  "caption": "...",
  "lyrics": "...",
  "response_format": "mp3",
  "error": {
    "stage": "audio_transcode",
    "message": "unsupported audio format"
  }
}

FAILED 是业务终态，HTTP 状态码仍为 200。

响应字段

字段	类型	说明
`status`	string	`PENDING`、`RUNNING`、`SUCCESS`、`FAILED`
`task`	string	提交时的任务类型
`caption`	string	提交时的风格描述
`lyrics`	string	提交或生成的歌词
`response_format`	string	输出格式
`sample_rate`	integer	输出采样率
`audio`	string（Base64）	生成音频，仅 `SUCCESS` 返回
`rewritten_caption`	string	服务端改写后的风格描述，仅 `SUCCESS` 返回
`rewritten_lyrics`	string	服务端生成或改写后的歌词，仅 `SUCCESS` 返回
`error`	object	失败原因，仅 `FAILED` 返回

失败阶段

`error.stage`	含义	建议处理
`audio_transcode`	音频无法解码、转码或采样率非法	检查音频格式、文件和参数
`no_speech_detected`	干声中未检测到有效人声	更换清晰且空白较少的干声
`censor`	文本或音频被安全审核拦截	调整内容后重新提交
`internal`	服务端内部错误	稍后重试并保留 `task_id`

查询错误码

HTTP	`error.type`	触发条件
400	`request_params_invalid`	请求体非法或缺少 `task_id`
401	`not_allowed`	鉴权 Header 缺失或无效
404	`task_not_found`	任务不存在或已超过保留期
429	`rate_limited`	查询过于频繁
503	`service_unavailable`	服务负载过高或结果读取失败

查询示例

curl -X POST "https://api.stepfun.com/v1/audio/music/query" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $STEP_API_KEY" \
  -d '{
    "task_id": "01959f5e-0f31-7a2b-9c4d-1234567890ab"
  }'

音频与输出约束

项目	约束
输入编码	音频原始字节的 Base64，不含 `data:` 前缀
输入容器	`wav`、`flac`、`opus`、`mp3`
输出格式	`wav`、`flac`、`opus`、`mp3`、`pcm`
输出采样率	原生 48 kHz 立体声，支持服务端重采样

推荐使用 MP3 输出以降低响应体积。PCM 为无文件头裸流，需按 48 kHz、16 bit、立体声自行解析。

合规说明

生成内容对外分发、发布或用于商业用途时，调用方应根据适用法律法规添加人工智能生成内容标识。

​服务地址

​能力范围

​通用约定

​请求头

​统一错误响应

​提交音乐生成任务

​请求参数

​参数适用矩阵

​参数说明

​器乐与歌词

​翻唱

​干声配乐

​Caption 改写

​输出时长

​歌词结构标签

​Caption 写法建议

​响应

​错误码

​调用示例

​查询任务结果

​请求参数

​任务状态

​进行中响应

​成功响应

​失败响应

​响应字段

​失败阶段

​查询错误码

​查询示例

​音频与输出约束

​合规说明

服务地址

能力范围

通用约定

请求头

统一错误响应

提交音乐生成任务

请求参数

参数适用矩阵

参数说明

器乐与歌词

翻唱

干声配乐

Caption 改写

输出时长

歌词结构标签

Caption 写法建议

响应

错误码

调用示例

查询任务结果

请求参数

任务状态

进行中响应

成功响应

失败响应

响应字段

失败阶段

查询错误码

查询示例

音频与输出约束

合规说明