查询任务

  • Flow Music 的任务查询接口
  • 与 Suno 系列的查询是同一个端点
  • 路径 /v1/music/tasks/{task_id}
GET/v1/music/tasks/{task_id}

认证

string必填

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

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

请求时在请求头中添加：

Authorization: Bearer YOUR_OAIRoute_KEY

请求参数

路径参数

string必填

提交任务时返回的 ID，取自提交响应里的 data[0].task_id。

查询参数

string可选

错误信息与提示文案的语言，默认 zh。

可选值：zh、en、ja、ko。

只影响错误描述的语言，不改变其他内容。

Flow Music 与 Suno 共用这一个查询端点。无论你提交的是 flowmusic 还是 suno 任务，都用同一个地址查。

响应

顶层

integer

状态码，成功为 200。

object

任务详情容器。

data 任务字段

data 的元素字段 · 9 项
string

任务 ID。

string

任务状态，取值 pending、processing、completed、failed。

integer

进度，0 到 100。

integer

创建时间，Unix 时间戳。

integer

完成时间，Unix 时间戳。

integer

实际耗时，单位秒。

number

实际扣费金额。失败通常为 0。

number

实际消耗的 credits。

object

生成结果。按能力不同结构不同，这是本接口最需要注意的地方。

result.music[] 音乐类任务

string

片段 ID。

string

标题。

string

时长，单位秒。注意是字符串形式的数值。

string

音频地址，m4a 格式。

string

WAV 地址。

string

视频地址，如视频渲染结果。

string

附加文件地址，如分轨 zip。

result.lyrics[] 歌词类任务

string

歌词标题。

string

歌词正文，带段落标记。

错误响应

error 的元素字段 · 4 项
string

错误描述。

string

错误类型，如 invalid_request、rate_limit_error。

string

出错的参数名。无特定参数时为空串。

string

错误码，如 task_not_found、rate_limit_error。

结果结构随能力变化

这是最容易踩的坑：同一个端点，不同任务类型返回的 result 结构不同。

任务类型结果位置
生成音乐result.music[]
生成歌词result.lyrics[]
分轨（Flow Music）result.music[].file_url
视频渲染result.music[].video_url 或 result.videoUrl
歌词时间轴result.alignment
BPM 分析result 下的速度字段

写解析代码时，先按任务类型分支，再取对应字段。指望一个通用的读取函数适配全部，会到处拿不到值。

duration_seconds 是字符串。直接参与算术会变成字符串拼接，需要先转数值。

轮询建议

任务类型间隔预期耗时
音乐生成3 到 5 秒30 到 120 秒
歌词、标签增强3 到 5 秒10 到 40 秒
下载任务2 秒通常 15 秒内
模型训练10 到 30 秒数分钟到 20 分钟

错误码

错误响应的格式、状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

使用示例

提交一个任务并拿到 task_id：

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