跳转到主要内容
POST
提交获取带时间戳歌词任务
  1. 提交后会返回 task_id。如果提供了 callback_url,当任务状态变为 finished 或 failed 时,系统会向 callback_url 发送 POST 请求。
  2. 无论是否提供 callback_url,都可以通过统一的查询音乐详情接口获取结果。

使用指南

  • 此接口获取已生成音轨的同步歌词及其精确时间戳
  • 可用于制作卡拉 OK 式显示、字幕或歌词可视化
  • 需要一个已完成且包含人声的音乐生成任务

参数详情

  • 必填参数:
    • task_id:先前音乐生成任务的唯一标识
    • audio_id:任务结果中具体音轨的标识
  • 这两个标识都可以从音乐生成接口的响应或其回调中获得

开发者说明

  • 此接口仅适用于包含人声的音轨
  • hoot_cer(字符错误率)值表示对齐精度,值越低表示越准确
  • 使用 waveform_data 可在歌词旁制作音频可视化效果

响应字段

  • aligned_words (array):带时间信息的歌词单词列表
    • word (string):歌词文本,可能包含 [Verse]、[Chorus] 等段落标记
    • start_s (number):单词开始时间(秒)
    • end_s (number):单词结束时间(秒)
    • success (boolean):该单词是否对齐成功
    • palign (number):对齐置信度分数
  • waveform_data (array):用于音频波形可视化的数值数据
  • hoot_cer (number):对齐精度分数(字符错误率)
  • is_streamed (boolean):表示该音频是否为流式音轨

授权

Authorization
string
header
必填

所有 API 接口都需要 Bearer Token 认证。

创建 API Key:登录 PoYo,进入 仪表盘 → API 密钥(poyo.ai/zh/dashboard/api-key),点击创建 Key。

在请求头中添加:

请求体

application/json
model
enum<string>
必填

API 模型标识符。

此接口必须为 get-timestamped-lyrics。

可用选项:
get-timestamped-lyrics
示例:

"get-timestamped-lyrics"

input
object
必填

获取带时间戳歌词的输入参数

callback_url
string<uri>

接收结果通知的 Webhook 回调 URL

示例:

"https://your-domain.com/callback"

响应

成功获取带时间戳的歌词

code
enum<integer>
必填

业务状态码。200 表示成功,其他值都表示请求失败。请务必检查这个字段:部分参数校验错误会以 HTTP 200 返回,响应体里的 code 为 400。

  • 200:成功
  • 400:请求参数无效
  • 401:API Key 缺失或无效
  • 402:积分不足
  • 403:没有权限
  • 404:资源不存在
  • 408:请求超时
  • 429:请求频率超限
  • 500:服务器内部错误
  • 502:上游服务错误
  • 503:服务暂不可用

详见错误码。

可用选项:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
示例:

200

data
object
必填