Skip to main content
POST
/
api
/
v1
/
lyrics
Generate Lyrics
curl --request POST \
  --url https://api.sunoapi.org/api/v1/lyrics \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "A song about peaceful night in the city",
  "callBackUrl": "https://api.example.com/callback"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}
Create original song lyrics using AI — without generating audio. Provide a descriptive prompt and a callback URL; you’ll receive a taskId immediately and the completed lyrics via your callback.

​
Lyrics Generation Process

Turn your concept into structured lyrics:

​
Step 1: Prompt Understanding

  • Theme & Mood Parsing: Extracts topic, tone, and perspective
  • Style Guidance: Interprets genre, era, and writing style hints
  • Structure Hints: Detects verse/chorus/bridge cues if provided

​
Step 2: Composition

  • Coherent Sections: Builds verses, choruses, and optional bridge/outro
  • Rhyme & Meter: Aims for natural phrasing and singable lines
  • Context Consistency: Keeps story, pronouns, and imagery aligned

​
Step 3: Delivery

  • Single-Stage Callback: Sends final lyrics to your callBackUrl when complete
  • Task Tracking: Use the returned taskId to correlate results in your system

​
Required Parameters

Both fields are mandatory:

​
prompt

  • Content Brief: Describe theme, mood, audience, and style
  • Clarity Wins: Concrete imagery and scene-setting improve results
  • Limit: Up to ~200 words recommended for best adherence

​
callBackUrl

  • Notification: Receives a single complete event with generated lyrics
  • Reliability: Your endpoint should accept JSON payloads
  • Correlation: Use taskId in the payload to match requests

​
Response Handling

​
Success Response (immediate)

  • taskId: Returned straight away to track the job
  • Status: Indicates the request was accepted
{
  "code": 200,
  "msg": "success",
  "data": { "taskId": "5c79****be8e" }
}

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
​
prompt
string
required

Detailed description of the desired lyrics content. Be specific about themes, moods, styles, and song structure you want. The more detailed your prompt, the more closely the generated lyrics will match your vision. The maximum word limit is 200 words.

Example:

"A song about peaceful night in the city"

​
callBackUrl
string<uri>
required

The URL to receive lyrics generation results when complete. Required. Unlike music generation, lyrics callback has only one stage: complete (generation finished). Alternatively, you can poll a details endpoint.

Example:

"https://api.example.com/callback"

Response

Request successful

​
code
enum<integer>

Status code. 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