Lyrics Generation API

POST /api/v1/lyrics/generate creates a structured lyrics package for music, MV, and editorial workflows. It can return synchronously when generation finishes quickly, or return 202 with a pollUrl while the task continues.

Use Producer lyrics when you only need a simple task-shaped lyric asset inside the Producer flow. Use this endpoint when you need a richer package: title, lyrics, language plan, hook, Suno-ready tags, Producer-ready sound prompt, notes, and token usage when available.

Generate

curl -X POST https://api.omnapi.com/api/v1/lyrics/generate \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: lyrics-demo-001" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a bilingual romantic pop song about meeting again on a rainy neon street.",
    "language": "Chinese",
    "languages": ["Chinese", "English"],
    "multilingualMode": "sectioned",
    "genre": "mandopop, synthpop",
    "mood": "romantic and cinematic",
    "vocalStyle": "airy female vocal",
    "durationSec": 140,
    "themeKeywords": ["rain", "neon", "reunion"],
    "extraGuidance": "Keep the chorus simple and memorable.",
    "config": {
      "metadata": {
        "orderId": "ord_123"
      }
    }
  }'

Body fields

Field	Type	Required	Notes
prompt	string	yes	Core brief, story, scene, or hook idea. Max 2000 chars.
mode	"grok" | "gpt"	—	Optional generation mode. Omit for the default.
language	string	—	Primary lyric language, or auto.
languages	string[]	—	Additional languages for multilingual lyrics.
multilingualMode	string	—	auto, sectioned, blended, or call_and_response.
genre, mood, vocalStyle	string	—	Musical direction.
perspective	string	—	first_person, second_person, third_person, or mixed.
themeKeywords	string[]	—	Short anchors for imagery and subject matter.
structure	string[]	—	Requested section order, such as Verse 1, Chorus, Bridge.
durationSec	number	—	Target duration, 30-480 seconds.
explicit	boolean	—	Whether explicit language is acceptable.
negativeConstraints	string[]	—	Styles, topics, or tropes to avoid.
extraGuidance	string	—	Additional constraints. Max 2000 chars.
config	object	—	Standard task config: priority, tags, metadata, webhookUrl.

Completed response

{
  "taskId": "task_01J...",
  "status": "COMPLETED",
  "modelPath": "grok/grok-4.20-beta-latest-non-reasoning/lyrics-generation",
  "creditsCharged": 12,
  "title": "Neon Rain",
  "lyrics": "[Verse 1]\n...",
  "languagePlan": {
    "primaryLanguage": "Chinese",
    "secondaryLanguages": ["English"],
    "mixStrategy": "Chinese verses with an English chorus hook.",
    "transliteration": null
  },
  "sectionOrder": ["Verse 1", "Chorus"],
  "hook": "Stay with me in the neon rain tonight",
  "suno": {
    "title": "Neon Rain",
    "prompt": "[Verse 1]\n...",
    "tags": "mandopop, synthpop, romantic, cinematic",
    "negativeTags": "heavy metal, aggressive rap"
  },
  "producer": {
    "title": "Neon Rain",
    "lyrics": "[Verse 1]\n...",
    "soundPrompt": "Romantic mandopop with synthpop sheen, airy female vocal..."
  },
  "notes": []
}

Accepted response

When generation needs more time, the endpoint returns 202:

{
  "taskId": "task_01J...",
  "status": "PROCESSING",
  "modelPath": "grok/grok-4.20-beta-latest-non-reasoning/lyrics-generation",
  "creditsRequired": 12,
  "message": "Lyrics task is still processing. Query the task endpoint for the final result.",
  "pollUrl": "/api/v1/tasks/task_01J..."
}

Poll the pollUrl or receive task.* webhooks when config.webhookUrl is set.

Related endpoints

Endpoint	Use when
POST /api/v1/lyrics/generate	You need a full structured lyric package and music-ready prompt fields.
POST /api/v1/producer/generate/lyrics	You want a simple Producer task result inside the Producer workflow.
POST /api/v1/subtitles	You already have audio and need timed lyrics or subtitle files.