跳转到主要内容
POST
/
api
/
v1
/
generate
/
get-timestamped-lyrics
获取带时间戳的歌词
curl --request POST \
  --url https://api.api.box/api/v1/generate/get-timestamped-lyrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "taskId": "5c79****be8e",
  "audioId": "e231****-****-****-****-****8cadc7dc",
  "musicIndex": 0
}'
{
  "code": 200,
  "msg": "success",
  "data": {
    "alignedWords": [
      {
        "word": "[Verse]\nWaggin'",
        "success": true,
        "startS": 1.36,
        "endS": 1.79,
        "palign": 0
      }
    ],
    "waveformData": [
      0,
      1,
      0.5,
      0.75
    ],
    "hootCer": 0.3803191489361702,
    "isStreamed": false
  }
}

​
参数选择逻辑

  1. audioId 和 musicIndex 的匹配优先级：
    • 如果只提供 audioId：按 audioId 匹配
    • 如果只提供 musicIndex：按索引位置匹配
    • 如果两者都提供：优先尝试 audioId，如果未找到则使用 musicIndex

​
开发者注意事项

  1. 时间戳值以秒为单位
  2. 返回的波形数据可用于音频可视化
  3. 对于纯音乐曲目（使用 instrumental=true 生成的），将没有歌词数据
  4. 典型用例：音乐播放器界面中的卡拉OK式歌词显示

Authorizations

​
Authorization
string
header
required

🔑 API 认证说明

所有接口都需要通过 Bearer Token 方式进行认证。

获取 API Key

  1. 访问 API Key 管理页面 获取您的 API Key

使用方式

在请求头中添加：

Authorization: Bearer YOUR_API_KEY

⚠️ 注意：

  • 请妥善保管您的 API Key，不要泄露给他人
  • 如果怀疑 API Key 泄露，请立即在管理页面重置

Body

application/json
​
taskId
string
required

音乐生成任务的任务ID。用于标识包含歌词的生成任务。

Example:

"5c79****be8e"

​
audioId
string

要获取歌词的特定音频ID。

  • 如果同时提供了 audioId 和 musicIndex，此参数优先。
  • 可选，但应提供 audioId 或 musicIndex 以标识确切的曲目。
Example:

"e231****-****-****-****-****8cadc7dc"

​
musicIndex
enum<number>

任务中曲目的索引（0或1）。

  • 仅当未提供 audioId 或未找到时使用。
  • 可选，但应提供 audioId 或 musicIndex 以标识确切的曲目。
Available options:
0,
1
Example:

0

Response

请求成功

​
code
enum<integer>

状态码说明

  • ✅ 200 - 请求成功
  • ⚠️ 400 - 参数错误
  • ⚠️ 401 - 没有访问权限
  • ⚠️ 404 - 请求方式或者路径错误
  • ⚠️ 405 - 调用超过限制
  • ⚠️ 413 - 主题或者prompt过长
  • ⚠️ 429 - 积分不足
  • ⚠️ 430 - 您的调用频率过高。请稍后再试。
  • ⚠️ 455 - 网站维护
  • ❌ 500 - 服务器异常
Available options:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
Example:

200

​
msg
string

当 code != 200 时，展示错误信息

Example:

"success"

​
data
object
⌘I