> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunoapi.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Timestamped Lyrics

> Retrieve timestamped lyrics for synchronized display during audio playback.

### Parameter Selection Logic

1. audioId parameter:
   * The audioId parameter is required to identify the exact track
   * Provides a unique identifier for the audio track within the generation task

### 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


## OpenAPI

````yaml /suno-api/suno-api.json POST /api/v1/generate/get-timestamped-lyrics
openapi: 3.0.0
info:
  title: intro
  description: API documentation for audio generation services
  version: 1.0.0
  contact:
    name: Technical Support
    email: support@sunoapi.org
servers:
  - url: https://api.sunoapi.org
    description: API Server
security:
  - BearerAuth: []
tags:
  - name: Music Generation
    description: Endpoints for creating and managing music generation tasks
  - name: Lyrics Generation
    description: Endpoints for lyrics generation and management
  - name: WAV Conversion
    description: Endpoints for converting music to WAV format
  - name: Vocal Removal
    description: Endpoints for vocal removal from music tracks
  - name: Music Video Generation
    description: Endpoints for generating MP4 videos from music tracks
  - name: Account Management
    description: Endpoints for account and credits management
paths:
  /api/v1/generate/get-timestamped-lyrics:
    post:
      summary: Get Timestamped Lyrics
      operationId: get-timestamped-lyrics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - taskId
                - audioId
              properties:
                taskId:
                  type: string
                  description: >-
                    The task ID of the music generation task. Required to
                    identify which generation task contains the lyrics.
                  example: 5c79****be8e
                audioId:
                  type: string
                  description: Audio ID of the track to retrieve lyrics for.
                  example: e231****-****-****-****-****8cadc7dc
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          alignedWords:
                            type: array
                            description: List of aligned lyrics words
                            items:
                              type: object
                              properties:
                                word:
                                  type: string
                                  description: Lyrics word
                                  example: |-
                                    [Verse]
                                    Waggin'
                                success:
                                  type: boolean
                                  description: Whether lyrics word is successfully aligned
                                  example: true
                                startS:
                                  type: number
                                  description: Word start time (seconds)
                                  example: 1.36
                                endS:
                                  type: number
                                  description: Word end time (seconds)
                                  example: 1.79
                                palign:
                                  type: integer
                                  description: Alignment parameter
                                  example: 0
                          waveformData:
                            type: array
                            description: Waveform data, used for audio visualization
                            items:
                              type: number
                            example:
                              - 0
                              - 1
                              - 0.5
                              - 0.75
                          hootCer:
                            type: number
                            description: Lyrics alignment accuracy score
                            example: 0.3803191489361702
                          isStreamed:
                            type: boolean
                            description: Whether it's streaming audio
                            example: false
              example:
                code: 200
                msg: success
                data:
                  alignedWords:
                    - word: |-
                        [Verse]
                        Waggin'
                      success: true
                      startS: 1.36
                      endS: 1.79
                      palign: 0
                  waveformData:
                    - 0
                    - 1
                    - 0.5
                    - 0.75
                  hootCer: 0.3803191489361702
                  isStreamed: false
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: |-
            # 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
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 404
            - 405
            - 413
            - 429
            - 430
            - 455
            - 500
        msg:
          type: string
          description: Error message when code != 200
          example: success
  responses:
    Error:
      description: Server error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        # 🔑 API Authentication


        All endpoints require authentication using Bearer Token.


        ## Get API Key


        1. Visit the [API Key Management Page](https://sunoapi.org/api-key) 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

````