POST
/
api
/
v1
/
generate
/
get-timestamped-lyrics
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
  }
}

Parameter Selection Logic

  1. audioId and musicIndex matching priority:
    • If only audioId is provided: Match by audioId
    • If only musicIndex is provided: Match by index position
    • If both are provided: Try audioId first, fall back to musicIndex if not found

Developer Notes

  1. Timestamp values are in seconds
  2. Returned waveform data can be used for audio visualization
  3. For instrumental tracks (generated with instrumental=true), no lyrics data will be available
  4. Typical use case: Karaoke-style lyrics display in music player interfaces

Authorizations

Authorization
string
header
required

🔑 API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

  1. Visit the API Key Management Page to obtain your API Key

Usage

Add to request headers:

Authorization: Bearer YOUR_API_KEY

⚠️ Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately from the management page

Body

application/json
taskId
string
required

The task ID of the music generation task. Required to identify which generation task contains the lyrics.

Example:

"5c79****be8e"

audioId
string

The specific audio ID to retrieve lyrics for.

  • Takes priority over musicIndex if both are provided.
  • Optional, but either audioId or musicIndex should be provided to identify the exact track.
Example:

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

musicIndex
enum<number>

The index of the track (0 or 1) within the task.

  • Used only if audioId is not provided or not found.
  • Optional, but either audioId or musicIndex should be provided to identify the exact track.
Available options:
0,
1
Example:

0

Response

Request successful

code
enum<integer>

Status Codes

  • ✅ 200 - Request successful
  • ⚠️ 400 - Invalid parameters
  • ⚠️ 401 - Unauthorized access
  • ⚠️ 404 - Invalid request method or path
  • ⚠️ 405 - Rate limit exceeded
  • ⚠️ 413 - Theme or prompt too long
  • ⚠️ 429 - Insufficient credits
  • ⚠️ 430 - Your call frequency is too high. Please try again later.
  • ⚠️ 455 - System maintenance
  • ❌ 500 - Server error
Available options:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
Example:

200

msg
string

Error message when code != 200

Example:

"success"

data
object