--- title: Suno Get-Timestamped-Lyrics url: https://runapi.ai/docs/api/suno/get-timestamped-lyrics.md canonical: https://runapi.ai/docs/api/suno/get-timestamped-lyrics locale: en --- # Suno Get-Timestamped-Lyrics ## Overview Use the get timestamped lyrics endpoint and read the result from the same response. ### Quick start 1. Create an API key and set it as RUNAPI_API_KEY. 2. Send a POST request whose body matches the request schema. 3. Read the result from the successful response body. ## Endpoint POST /api/v1/suno/get_timestamped_lyrics Base URL: https://runapi.ai API version: v1 Authentication: Authorization: Bearer YOUR_API_TOKEN ## Supported models Open a model page for current pricing, rate limits, and commercial-usage details. - [Suno](/models/suno) ## Request schema Send only the fields declared for this endpoint. ### Request body ```json { "audio_id": { "description": "Audio ID within the source task.", "required": true, "type": "string" }, "task_id": { "description": "Source task ID.", "required": true, "type": "string" } } ``` ## Success response HTTP 200 - POST /api/v1/suno/get_timestamped_lyrics ### Response schema ```json { "properties": { "aligned_words": { "items": { "properties": { "end_time": { "type": "number" }, "palign": { "type": "number" }, "start_time": { "type": "number" }, "success": { "type": "boolean" }, "word": { "type": "string" } }, "required": [ "word", "success", "start_time", "end_time", "palign" ], "type": "object", "unevaluatedProperties": false }, "type": "array" }, "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "hoot_cer": { "type": "number" }, "is_streamed": { "type": "boolean" }, "waveform_data": { "items": { "type": "number" }, "type": "array" } }, "required": [ "aligned_words", "waveform_data", "hoot_cer", "is_streamed", "billing" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "aligned_words": [ { "end_time": 0.6, "palign": 0.98, "start_time": 0.0, "success": true, "word": "Welcome" } ], "billing": { "refund": null, "reservation": null, "settlement": null }, "hoot_cer": 0.03, "is_streamed": false, "waveform_data": [ 0.1, 0.4, 0.2 ] } ``` ## Errors HTTP 401 - POST /api/v1/suno/get_timestamped_lyrics This response has no body. ## Errors HTTP 400 - POST /api/v1/suno/get_timestamped_lyrics ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "task_id_is_required", "message": "task_id is required" } } ``` ## Errors HTTP 402 - POST /api/v1/suno/get_timestamped_lyrics ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "insufficient_balance", "message": "Insufficient balance" } } ``` ## Errors HTTP 403 - POST /api/v1/suno/get_timestamped_lyrics ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "api_token_credit_limit_exceeded", "message": "API key credit limit exceeded" } } ``` ## Errors HTTP 409 - POST /api/v1/suno/get_timestamped_lyrics ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "request_conflict", "message": "The request uses features that are not supported for the selected model" } } ``` ## Errors HTTP 429 - POST /api/v1/suno/get_timestamped_lyrics ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "rate_limited", "message": "Rate limit reached. Please retry later." } } ``` ## Errors HTTP 503 - POST /api/v1/suno/get_timestamped_lyrics ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "error": { "code": "service_unavailable", "message": "Service under maintenance, please try again later" } } ``` ## Errors HTTP 504 - POST /api/v1/suno/get_timestamped_lyrics ### Response schema ```json { "properties": { "billing": { "properties": { "refund": { "oneOf": [ { "properties": { "refunded_at": { "type": "string" } }, "required": [ "refunded_at" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "reservation": { "oneOf": [ { "properties": { "amount_cents": { "type": "integer" } }, "required": [ "amount_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] }, "settlement": { "oneOf": [ { "properties": { "amount_micro_cents": { "type": "integer" }, "charged_amount_cents": { "type": "integer" } }, "required": [ "charged_amount_cents", "amount_micro_cents" ], "type": "object", "unevaluatedProperties": false }, { "enum": [ null ] } ] } }, "required": [ "reservation", "settlement", "refund" ], "type": "object", "unevaluatedProperties": false }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object", "unevaluatedProperties": false } }, "required": [ "error" ], "type": "object", "unevaluatedProperties": false } ``` ### Response example ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "error": { "code": "timeout_error", "message": "The request timed out" } } ``` ## Generated Code Samples Use cURL directly, or install an SDK for your language. Each sample submits the validated request shown in this reference. ### curl ```curl curl -X POST https://runapi.ai/api/v1/suno/get_timestamped_lyrics \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"task_id":"tsk_source_music","audio_id":"audio_reference"}' ``` ### javascript #### Install ```bash npm install @runapi.ai/suno ``` ```javascript import { SunoClient } from "@runapi.ai/suno"; const client = new SunoClient({ apiKey: process.env.RUNAPI_API_KEY }); const result = await client.getTimestampedLyrics.run({ "task_id": "tsk_source_music", "audio_id": "audio_reference" }); ``` ### python #### Install ```bash pip install runapi-suno ``` ```python import os from runapi.suno import SunoClient client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"]) result = client.get_timestamped_lyrics.run( task_id="tsk_source_music", audio_id="audio_reference" ) ``` ### go #### Install ```bash go get github.com/runapi-ai/suno-sdk/go@latest ``` ```go package main import ( "context" "log" "os" "github.com/runapi-ai/core-sdk/go/option" suno "github.com/runapi-ai/suno-sdk/go/suno" ) func main() { client, err := suno.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY"))) if err != nil { log.Fatal(err) } result, err := client.GetTimestampedLyrics.Run(context.Background(), suno.GetTimestampedLyricsParams{ TaskID: "tsk_source_music", AudioID: "audio_reference", }) if err != nil { log.Fatal(err) } _ = result } ``` ### ruby #### Install ```bash gem install runapi-suno ``` ```ruby require "runapi/suno" client = RunApi::Suno::Client.new(api_key: ENV.fetch("RUNAPI_API_KEY")) result = client.get_timestamped_lyrics.run( task_id: "tsk_source_music", audio_id: "audio_reference" ) ``` ### java #### Install ```kotlin implementation("ai.runapi:runapi-suno") ``` ```java import ai.runapi.suno.SunoClient; import ai.runapi.suno.types.GetTimestampedLyricsParams; import ai.runapi.suno.types.GetTimestampedLyricsResponse; public final class Example { public static void main(String[] args) { SunoClient client = SunoClient.builder() .apiKey(System.getenv("RUNAPI_API_KEY")) .build(); GetTimestampedLyricsResponse result = client.getTimestampedLyrics().run( GetTimestampedLyricsParams.builder() .taskId("tsk_source_music") .audioId("audio_reference") .build() ); } } ``` ### php #### Install ```bash composer require runapi-ai/suno ``` ```php getTimestampedLyrics->run([ "task_id" => "tsk_source_music", "audio_id" => "audio_reference" ]); ``` ## Related Guides - [Authentication](/docs/guides/authentication) - [Quickstart](/docs/guides/task-api/quickstart)