Generate Suno lyrics

Use this workflow for Suno lyric candidates. For a richer language plan, see structured lyrics.

Generate lyrics

Call POST /api/v1/suno/lyrics when you need lyrics without starting song generation. Set candidates: 2 for two independently generated candidates in one Task. A paired Task succeeds only after two distinct candidates, A and B, both complete. One delivered candidate is not reported as a successful pair. The operation returns a Task receipt; poll GET /api/v1/tasks/{taskId} for the result.

Field	Type	Notes
prompt	string, max 3,000	Required subject, story, mood, or structural direction
candidates	integer literal 1 or 2	Omit or send 1 for one result; 2 requests paired candidates for the same operation price. Strings and 0 are invalid.
lyricsModel	string, max 100	Single-candidate requests use the stable default workflow; when candidates is 2, the only accepted value is default
source	string, max 100	With candidates: 2, an optional caller label retained with the Task for audit; it is not a model selector
config	object	Priority, webhook URL, tags, and metadata

curl -X POST https://api.omnapi.com/api/v1/suno/lyrics \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "bittersweet indie pop about moving away", "candidates": 2 }'

The immediate response is the same Task create receipt shape used by export. After completion, read the generated text from the Task’s outputResults and standardized text resources. Paired candidates remain part of one Task, one billing decision, and one idempotency scope. The two resources preserve their A/B order.

Each completed text resource can also contain metadata.stylePrompt. For compatibility, the same complete style prompt is returned as the single item in metadata.tags; it is not split on commas. Style expansion is best-effort. If it is temporarily unavailable, the lyrics Task still succeeds, those optional fields are omitted, and outputResults.warnings can include SUNO_STYLE_UPSAMPLE_UNAVAILABLE.

{
  "type": "TEXT",
  "index": 0,
  "id": "lyrics_a",
  "content": "[Verse 1]\n...",
  "metadata": {
    "stylePrompt": "Intimate indie folk built around fingerpicked acoustic guitar...",
    "tags": [
      "Intimate indie folk built around fingerpicked acoustic guitar..."
    ]
  }
}

If either candidate is not delivered, the Task fails atomically, is refunded, and exposes SUNO_LYRICS_PAIR_TEMPORARILY_UNAVAILABLE with retryable: true. Retry later as a new request. Idempotency-Key remains optional; when the failed request supplied one, use a new value for that new attempt.