生成音乐

Flow Music 的主生成接口，异步任务
与 Suno 共用同一个端点，靠 model 字段区分
单次请求出 1 首

POST/v1/music/generations

认证

string必填

所有接口均使用 Bearer Token 进行认证。

获取 API Key：访问控制台创建。

请求时在请求头中添加：

Authorization: Bearer YOUR_OAIRoute_KEY

请求参数

string必填

固定填 flowmusic，大小写不敏感。

注意：同一个端点也承载 Suno，那边填 suno。两者靠这个字段分流。

string条件必填

音乐风格与音色描述提示词。例如「明快的流行乐，带钢琴前奏」。

sound_prompt 与 lyrics 至少传一个，不能同时为空。

string条件必填

歌词正文。可以先调「生成歌词」接口拿到再回填。

与 sound_prompt 至少传一个。

string可选

生成音乐的标题。

string可选

每分钟节拍数。类型是字符串，例如 "120"，数值须不小于 1。

integer可选

生成时长，取值 1 到 240，单位秒。

string可选

复现用的随机种子，任意字符串。相同请求与相同 seed 结果相似，但不保证完全一致。

提交响应

integer

状态码，成功为 200。

data[] 的元素字段 · 2 项

string

任务状态，提交成功时为 submitted。

string

任务唯一标识，用于后续查询。

任务查询响应

用 GET /v1/music/tasks/{task_id} 查询。

data 的元素字段 · 8 项

string

任务 ID。

string

已完成时为 completed。

integer

进度百分比。

integer

创建时间，Unix 秒。

integer

完成时间，Unix 秒。

integer

实际耗时，单位秒。

number

费用，美元。

number

积分消耗。

data.result 的元素字段

array

生成的音乐列表。

music[] 元素字段

string

音频片段 UUID。

string

曲目标题。

string

时长，字符串形式的浮点秒数，例如 "184.2"。

string

ISO 8601 时间戳。

string

该曲使用的歌词文本。

string

歌词 UUID。

array

时间标记，二元组数组，形如 [[10,12],[212,36]]，元素为整数对。

string

音频地址，.m4a 格式。

string

WAV 格式地址。

string

封面图地址，.jpg 格式。

与 Suno 的差异

项目	Flow Music	Suno
`model` 取值	`flowmusic`	`suno`
提示词字段	`sound_prompt`	`prompt`
时长字段	`length`（秒，1–240）	`duration`（秒，10–360）
节拍控制	`bpm`	无
结果时长字段	`duration_seconds`（字符串）	`duration`（数字）
歌词时间轴	`lyrics_timing_markers`	无
追加格式	额外给 `wav_url`	无

Item	Flow Music	Suno
`model` value	`flowmusic`	`suno`
Prompt field	`sound_prompt`	`prompt`
Length field	`length` (seconds, 1–240)	`duration` (seconds, 10–360)
Tempo control	`bpm`	None
Result duration field	`duration_seconds` (string)	`duration` (number)
Lyrics timeline	`lyrics_timing_markers`	None
Extra format	An additional `wav_url`	None

错误

HTTP	type	code	message
400	invalid_request	invalid_request	sound_prompt 与 lyrics 不能同时为空
429	rate_limit_error	rate_limit_error	当前分组容量饱和，请稍后重试

duration_seconds 是字符串不是数字。直接做算术会得到字符串拼接的结果，需要先 float() 或 Number() 转换。

更多状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

HTTP	type	code	message
400	invalid_request	invalid_request	sound_prompt and lyrics can't both be empty
429	rate_limit_error	rate_limit_error	Current group capacity is saturated; retry later

duration_seconds is a string, not a number. Doing arithmetic on it concatenates strings instead; convert with float() or Number() first.

For more status codes and retry guidance see Error codes and rate limits; for troubleshooting steps on common errors see the FAQ.

使用示例

提交一个任务并拿到 task_id：

提交成功只表示任务已受理。真正的产物要拿返回的 task_id 去任务查询接口轮询，status 变成 completed 之后才有结果。