音乐生成（Flow Music）

flowmusic（Lyria 3 Pro / Lyria 3.5）：生成音乐、歌词、延伸、片段替换、Cover 改编、词曲分离、音乐视频，异步，用 GET /v1/music/tasks/{task_id} 查询

POST/v1/music/generations

POST/v1/music/generations/{operation}

GET/v1/music/tasks/{task_id}

Flow Music 与 Suno 共用同一套异步任务接口，用请求体中的 model: "flowmusic" 区分。每次请求生成一首音乐。所有接口都需要 API Key：Authorization: Bearer sk-lt-...，详见鉴权。

项	值
模型	`flowmusic`（大小写不敏感）
版本	默认 Lyria 3 Pro；传 `version: "lyria-3.5"` 使用 Lyria 3.5，同价
模式	异步（提交 → 轮询 `GET /v1/music/tasks/{task_id}`）
计费	按操作固定计费，失败自动退款
媒体保留	结果中的音频、视频、分轨文件保留 3 天，请及时转存

快速开始

curl https://api.vibelab.me/v1/music/generations \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flowmusic",
    "title": "My Song",
    "sound_prompt": "upbeat pop music with piano",
    "bpm": "120",
    "length": 60
  }'

响应示例：

{
  "code": 200,
  "data": [
    { "status": "submitted", "task_id": "at_0198f0a0-1111-7777-8888-999999999999" }
  ]
}

submitted 只表示任务已受理，用 task_id 调用查询任务取结果。

模式选择

模式	入口	怎么传参
生成音乐	`POST /v1/music/generations`	`sound_prompt`、`lyrics` 等，见请求参数
其它操作	`POST /v1/music/generations/{operation}`	路径后缀选操作，用 `clip_id` 引用源音乐，见操作列表

*FlowMusic 路径只属于 flowmusic，省略 model 时按路径推断为 flowmusic。

请求参数

生成音乐

平台只校验 JSON 结构，字段取值由上游校验。

参数	类型	必填	默认	说明
`model`	string	是	-	`flowmusic`（大小写不敏感）
`version`	string	否	Lyria 3 Pro	`lyria-3.5` 使用 Lyria 3.5
`sound_prompt`	string	否	-	音乐风格或声音描述
`lyrics`	string	否	-	歌词，可先调用 `lyricsFlowMusic` 生成后回填
`title`	string	否	-	标题
`bpm`	string	否	-	每分钟节拍数，必须 ≥ 1
`length`	integer	否	-	生成时长（秒）
`seed`	string	否	-	随机种子，用于复现结果

操作列表

除生成音乐外，其它操作统一为 POST /v1/music/generations/{operation}，请求体都需带 model: "flowmusic"。价格为积分/次，以定价页为准。

`{operation}`	功能	主要参数	价格
（无）	生成音乐	见上节	0.75
`lyricsFlowMusic`	生成歌词	`prompt`（≤ 3000 字符）	0.25
`extendFlowMusic`	音乐延伸	`clip_id`、`extend_from_s`、`extend_s`、`instruction`、`version`	0.75
`replaceFlowMusic`	片段替换	`clip_id`、`start_s`、`end_s`、`instruction`、`version`	0.75
`coverFlowMusic`	Cover 改编	`clip_id`、`instruction`、`strength`、`version`	0.75
`stemsFlowMusic`	词曲分离（返回 zip）	`clip_id`	0.75
`uploadAudioFlowMusic`	导入外部音频，换取 `clip_id`	`audio_url`（公网可访问）	0.125
`downloadAudioFlowMusic`	下载指定格式音频	`clip_id`、`format`	0.25
`videoClipFlowMusic`	音乐视频渲染	`clip_id`、`preset`（默认 `simple`）	0.25

延伸、替换、Cover 都可以传 version: "lyria-3.5" 使用 Lyria 3.5，价格相同；title、seed 为可选参数。

引用源音乐

延伸、替换、Cover、词曲分离、下载、音乐视频都用 clip_id 指定源音乐：取自已成功任务的 result.music[].clip_id。导入自己的音频请先调用 uploadAudioFlowMusic，完成后从 result.music[0].clip_id 取值。

curl https://api.vibelab.me/v1/music/generations/extendFlowMusic \
  -H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flowmusic",
    "clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
    "extend_from_s": 30,
    "extend_s": 20,
    "instruction": "加入更明亮的合成器旋律"
  }'

只能引用自己账户下已成功任务产出的 clip_id，否则返回 400 invalid_source_reference。

请求示例

最小请求体见快速开始（生成音乐）与上节的延伸示例；其它操作把 {operation} 换成操作列表中的后缀，带上对应参数即可。

响应

提交响应见快速开始。查询任务：

GET/v1/music/tasks/{task_id}

{
  "code": 200,
  "data": {
    "id": "at_0198f0a0-1111-7777-8888-999999999999",
    "status": "completed",
    "progress": 100,
    "created": 1783413241,
    "cost": 0.075,
    "credits_cost": 0.75,
    "result": {
      "music": [
        {
          "clip_id": "a41aade4-993e-4d28-b56f-d97e7ef7167c",
          "title": "My Song",
          "duration_seconds": "181.70666667",
          "audio_url": "https://...",
          "wav_url": "https://..."
        }
      ]
    }
  }
}

字段	类型	说明
`data.id`	string	任务 ID（`at_` 前缀）
`data.status`	string	`pending` / `processing` / `completed`（终态）/ `failed`（终态）
`data.progress`	integer	进度 0 到 100，是否完成以 `status` 为准
`data.created`	integer	创建时间，Unix 秒
`data.credits_cost` / `data.cost`	number	本次扣费，积分 / 美元（10 积分 = 1 美元），结算后返回
`data.result`	object	完成后的结果，结构随操作不同（见下）
`data.error`	object	失败时返回：`message`、`type`（`task_failed`）、`code`（`task_failed` 或 `timeout`）

结果结构随操作不同：音乐在 result.music[]；歌词在 result.lyrics[]；词曲分离返回 file_url（zip）；音乐视频返回 video_url；下载返回指定格式的 audio_url。
结果中的媒体地址是限时签名链接，每次查询都会重新签发；文件自任务完成起保留 3 天，过期后对应字段为空字符串。

计费

提交时按操作价格预扣，任务成功后结算；失败或超时自动退款。
实际扣费以终态任务中的 credits_cost 和定价页为准。

错误

错误体为 {"error": {"message": "...", "type": "...", "code": "...", "request_id": "..."}}（type 与 code 相同），通用错误码见错误码。本接口常见错误：

HTTP	code	触发场景	处理
`400`	`invalid_request_error`	JSON 不合法、字段类型错误（如 `clip_id` 不是非空字符串）	按 `message` 修正请求体
`400`	`invalid_source_reference`	`clip_id` 不存在，或不属于当前账户的已成功任务	使用自己账户已成功任务产出的 `clip_id`
`404`	`not_found`	操作名不存在，或操作与 `model` 不匹配	核对操作列表的 `{operation}`
`404`	`model_not_found`	`model` 不是 `suno` / `flowmusic`，或该模型没有可售价格	核对 `model`
`404`	`task_not_found`	任务不存在或不属于当前账户	核对 `task_id`
`429`	`media_concurrency_exceeded`	用户或 API Key 的媒体并发超限（响应带 `Retry-After`）	稍后重试
`502`	`upstream_error`	音乐服务暂时不可用	指数退避重试，已预扣的费用会退回
`503`	`no_available_channel`	当前没有可用的音乐生成通道	指数退避重试

余额不足返回 402 insufficient_credits。

注意事项

用 clip_id 引用源音乐 → 只能取自本账户已成功任务的 result.music[].clip_id，或 uploadAudioFlowMusic 的结果。
媒体链接 → 3 天后失效，请及时转存。

音乐生成（Flow Music）

本页内容