# Get Suno Timestamped Lyrics

> Audio Generation

Retrieve timestamped lyrics using a completed Suno task ID (`taskId`) and audio ID (`audioId`).

`alignedWords[].startS` and `alignedWords[].endS` are measured in seconds.

**cURL example:**

```bash
curl --request POST 'https://api.modelverse.cn/v1/sunoapi/get-timestamped-lyrics' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "taskId": "<suno-task-id>",
    "audioId": "<suno-audio-id>"
  }'
```

## Endpoint

`POST https://api.modelverse.cn/v1/sunoapi/get-timestamped-lyrics`

## Request Body

## Responses

- **200** — Lyrics retrieved successfully.
- **400** — Invalid request parameters, such as a missing or empty `taskId` or `audioId`.
- **default** — Upstream or server error response.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "Suno Timestamped Lyrics API",
    "version": "1.0.0",
    "description": "Synchronous API for retrieving timestamped lyrics from Suno.\nReturns aligned lyrics and waveform data for a Suno music task ID and audio ID.\nThis endpoint does not require a `model` field, is not billed, and does not write model usage records.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint."
    }
  ],
  "tags": [
    {
      "name": "Suno",
      "description": "Suno audio information queries."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/sunoapi/get-timestamped-lyrics": {
      "post": {
        "tags": [
          "Suno"
        ],
        "operationId": "getSunoTimestampedLyrics",
        "summary": "Get Suno Timestamped Lyrics",
        "description": "Retrieve timestamped lyrics using a completed Suno task ID (`taskId`) and audio ID (`audioId`).\n\n`alignedWords[].startS` and `alignedWords[].endS` are measured in seconds.\n\n**cURL example:**\n\n```bash\ncurl --request POST 'https://api.modelverse.cn/v1/sunoapi/get-timestamped-lyrics' \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"taskId\": \"<suno-task-id>\",\n    \"audioId\": \"<suno-audio-id>\"\n  }'\n```\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SunoTimestampedLyricsRequest"
              },
              "example": {
                "taskId": "<suno-task-id>",
                "audioId": "<suno-audio-id>"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lyrics retrieved successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoTimestampedLyricsResponse"
                },
                "example": {
                  "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
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters, such as a missing or empty `taskId` or `audioId`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoTimestampedLyricsErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Upstream or server error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SunoTimestampedLyricsErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "ModelVerse API key."
      }
    },
    "schemas": {
      "SunoTimestampedLyricsRequest": {
        "type": "object",
        "description": "Only the following two fields are required; extra fields are ignored by the server.",
        "required": [
          "taskId",
          "audioId"
        ],
        "properties": {
          "taskId": {
            "type": "string",
            "minLength": 1,
            "description": "A successfully generated Suno music task ID.",
            "example": "234dde9c8914e77e4d4fae0a1742a644"
          },
          "audioId": {
            "type": "string",
            "minLength": 1,
            "description": "The audio ID of the corresponding track in the Suno task.",
            "example": "cd508659-ecd2-402b-ac8d-54bbb1c4805e"
          }
        }
      },
      "SunoTimestampedLyricsResponse": {
        "type": "object",
        "description": "The successful response fields follow the Suno response structure.",
        "properties": {
          "code": {
            "type": "integer",
            "description": "Response code."
          },
          "msg": {
            "type": "string",
            "description": "Response message."
          },
          "data": {
            "$ref": "#/components/schemas/SunoTimestampedLyricsData"
          }
        }
      },
      "SunoTimestampedLyricsData": {
        "type": "object",
        "properties": {
          "alignedWords": {
            "type": "array",
            "description": "List of aligned lyric words.",
            "items": {
              "$ref": "#/components/schemas/SunoAlignedWord"
            }
          },
          "waveformData": {
            "type": "array",
            "description": "Audio waveform data.",
            "items": {
              "type": "number"
            }
          },
          "hootCer": {
            "type": "number",
            "description": "Lyric alignment accuracy score."
          },
          "isStreamed": {
            "type": "boolean",
            "description": "Whether the audio is streamed."
          }
        }
      },
      "SunoAlignedWord": {
        "type": "object",
        "properties": {
          "word": {
            "type": "string",
            "description": "Lyric word."
          },
          "success": {
            "type": "boolean",
            "description": "Whether this lyric segment was aligned successfully."
          },
          "startS": {
            "type": "number",
            "description": "Start time of the lyric segment, in seconds."
          },
          "endS": {
            "type": "number",
            "description": "End time of the lyric segment, in seconds."
          },
          "palign": {
            "type": "integer",
            "description": "Alignment parameter."
          }
        }
      },
      "SunoTimestampedLyricsErrorResponse": {
        "type": "object",
        "description": "Error response object; actual fields may vary.",
        "properties": {
          "code": {
            "type": "integer",
            "description": "Error code."
          },
          "msg": {
            "type": "string",
            "description": "Error message."
          }
        }
      }
    }
  }
}
```