歌词时间轴

生成逐句对齐的歌词时间轴，用于卡拉 OK 类应用，异步任务
结果含对齐数据与波形数据
只返回数据，不产出音频

POST/v1/music/generations/alignedLyrics

认证

string必填

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

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

请求时在请求头中添加：

Authorization: Bearer YOUR_OAIRoute_KEY

请求参数

string可选

音频模型，默认 suno。

string必填

生成源音轨那次任务的 task_id。缺失或无法解析源音轨时，提交阶段直接返回 400。

integer可选

引用源任务结果 data.result.music[] 中的第几首，默认 1，从 1 开始。一次生成通常 2 首。

本端点没有 version 参数，传入会被忽略，不影响计费。

响应

integer

响应状态码。

data[] 的元素字段 · 2 项

string

任务状态，取值 submitted。

string

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

轮询结果

result 的元素字段 · 2 项

array

逐句对齐结果，优先读取这个字段。

array

波形数据，优先读取。

music[] 的元素字段 · 3 项

string

历史任务可能返回该字段。

string

历史任务可能返回该字段。

array

历史任务可能返回该字段。

返回结构有新旧两套。新任务读 result.alignment 与 result.waveform_data；老任务的数据在 music[] 下的三个字段里。接的时候按这两个位置分别兜底，否则老数据会读出空值。

怎么用这份数据

卡拉 OK 类应用需要三样东西：每句歌词、该句的起止时间、当前播放位置。

// 播放时按时间轴滚动高亮
function highlight(audio, alignment) {
  audio.addEventListener("timeupdate", () => {
    const t = audio.currentTime;

    const idx = alignment.findIndex(
      (line) => t >= line.start && t < line.end
    );

    document.querySelectorAll(".lyric-line").forEach((el, i) => {
      el.classList.toggle("active", i === idx);
    });
  });
}

字段名（start、end）以实际返回为准，第一次接的时候先打印一条看结构。

waveform_data 可以用来画波形进度条，比单纯的时间条更有节奏感。

A karaoke-style app needs three things: each lyric line, that line's start and end times, and the current playback position.

// Scroll-and-highlight along the timeline during playback
function highlight(audio, alignment) {
  audio.addEventListener("timeupdate", () => {
    const t = audio.currentTime;

    const idx = alignment.findIndex(
      (line) => t >= line.start && t < line.end
    );

    document.querySelectorAll(".lyric-line").forEach((el, i) => {
      el.classList.toggle("active", i === idx);
    });
  });
}

The field names (start, end) follow what's actually returned; print one entry to check the structure the first time you integrate.

waveform_data can drive a waveform progress bar, which feels more rhythmic than a plain time bar.

错误码

HTTP	type	说明
400	invalid_request_error	请求参数无效
401	authentication_error	身份验证失败，请检查API密钥
402	payment_required	账户余额不足
429	rate_limit_error	请求过于频繁

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

HTTP	type	Notes
400	invalid_request_error	Invalid request parameters
401	authentication_error	Authentication failed; check the API key
402	payment_required	Insufficient account balance
429	rate_limit_error	Too many requests

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 之后才有结果。