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

For each new logical operation, set and save a fresh REQUEST_KEY once. Reuse it with the exact same route and body only when recovering that operation. Use a different saved key when trying a different example or export format.

export REQUEST_KEY="$(uuidgen)"

curl -X POST https://api.omnapi.com/api/v1/lyrics/generate \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -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

Unknown fields are not accepted.

Required applies within the containing object or alternative. Expand nested objects only when supplying that value.

Field and type	Requirement	Description and constraints
promptstring	Required	Core song brief, story, scene, or hook idea.Maximum characters: 2000.
configobject	Optional	Standard task configuration: priority, tags, metadata, and webhookUrl.
config.metadataobject	Optional	Free-form caller metadata, echoed back on read. Stored as opaque JSON; the server never mutates it.
config.prioritynumber	Optional	Task priority 1-10 (higher = sooner). Default 5.Minimum: 1. Maximum: 10. Default: 5.
config.tagsarray<string>	Optional	Free-form labels for filtering. Up to 20, 100 chars each.Maximum items: 20.
config.tags[]string	Each item	Maximum characters: 100.
config.webhookUrlstring	Optional	URL to receive task.* lifecycle events via the central webhook service.Format: uri.
durationSecnumber	Optional	Target duration in seconds.Minimum: 30. Maximum: 480.
explicitboolean	Optional	Whether explicit language is acceptable.
extraGuidancestring	Optional	Additional creative guidance or constraints.Maximum characters: 2000.
genrestring	Optional	Requested musical genre direction.Maximum characters: 200.
languagestring	Optional	Primary lyric language. Use 'auto' to let the model decide.Maximum characters: 80.
languagesarray<string>	Optional	Additional languages to include or consider.
languages[]string	Each item	Additional languages to consider for multilingual lyrics.Maximum characters: 80.
mode"gpt"	Optional	Lyrics generation mode. GPT is the supported mode.
moodstring	Optional	Requested musical or visual mood.Maximum characters: 200.
multilingualMode"auto" | "sectioned" | "blended" | "call_and_response"	Optional	How multiple languages should be mixed.
negativeConstraintsarray<string>	Optional	Topics, styles, or tropes the output should avoid.
negativeConstraints[]string	Each item	Styles, topics, or tropes to avoid.Maximum characters: 80.
perspective"first_person" | "second_person" | "third_person" | "mixed"	Optional	Requested lyric narrative perspective.
structurearray<string>	Optional	Requested lyric section order.
structure[]string	Each item	Requested section order, e.g. Verse 1, Chorus, Bridge.Maximum characters: 50.
themeKeywordsarray<string>	Optional	Short theme keywords to anchor the lyrics.
themeKeywords[]string	Each item	Maximum characters: 60.
vocalStylestring	Optional	Requested vocal performance direction.Maximum characters: 200.

Completed response

Expand the complete JSON example

HTTP 200 · Complete response example

{
  "taskId": "task_01J...",
  "status": "COMPLETED",
  "model": "gpt-4.1-mini",
  "modelPath": "gpt/gpt-4.1-mini/lyrics-generation",
  "creditsCharged": 8,
  "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": [],
  "usage": {
    "promptTokens": 520,
    "completionTokens": 860,
    "totalTokens": 1380
  }
}

usage is optional. When present, its token counters describe the completed lyrics generation call.

Accepted response

When generation needs more time, the endpoint returns 202:

HTTP 202 · Complete response example

{
  "taskId": "task_01J...",
  "status": "PROCESSING",
  "modelPath": "gpt/gpt-4.1-mini/lyrics-generation",
  "creditsRequired": 8,
  "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.