Skip to main content
POST
Submit Get Timestamped Lyrics Task
  1. After submission, a task_id will be returned. If you provided a callback_url, when the task status becomes finished or failed, a POST request will be sent to the callback_url.
  2. Regardless of whether callback_url is provided, you can retrieve the response result through the unified Query Music Detail endpoint.

Usage Guide

  • This endpoint retrieves synchronized lyrics with precise timestamps for generated audio tracks
  • Use this to create karaoke-style displays, subtitles, or lyric visualizations
  • Requires a completed music generation task with vocals

Parameter Details

  • Required parameters:
    • task_id: The unique identifier from a previous music generation task
    • audio_id: The specific audio track identifier from the task result
  • Both identifiers are obtained from the response of music generation endpoints or their callbacks

Developer Notes

  • This endpoint only works with audio tracks that contain vocals
  • The hoot_cer (Character Error Rate) value indicates alignment precision - lower values mean better accuracy
  • Use waveform_data for creating audio visualizations alongside the lyrics

Response Fields

  • aligned_words (array): List of lyric words with timing information
    • word (string): The lyric text, may include section markers like [Verse], [Chorus]
    • start_s (number): Word start time in seconds
    • end_s (number): Word end time in seconds
    • success (boolean): Whether the word was successfully aligned
    • palign (number): Alignment confidence score
  • waveform_data (array): Numerical data for audio waveform visualization
  • hoot_cer (number): Alignment precision score (Character Error Rate)
  • is_streamed (boolean): Indicates if the audio is a streamed track

Authorizations

Authorization
string
header
required

All API endpoints require Bearer Token authentication.

Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.

Add it to the request header:

Body

application/json
model
enum<string>
required

API model identifier.

Must be get-timestamped-lyrics for this endpoint.

Available options:
get-timestamped-lyrics
Example:

"get-timestamped-lyrics"

input
object
required

Input parameters for retrieving timestamped lyrics

callback_url
string<uri>

Webhook callback URL for result notifications

Example:

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

Response

Timestamped lyrics retrieved successfully

code
enum<integer>
required

Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.

  • 200: Success
  • 400: Invalid request parameters
  • 401: Missing or invalid API key
  • 402: Insufficient credits
  • 403: Permission denied
  • 404: Resource not found
  • 408: Request timeout
  • 429: Rate limit exceeded
  • 500: Internal server error
  • 502: Upstream service error
  • 503: Service unavailable

See Error Codes for details.

Available options:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
Example:

200

data
object
required