Skip to content
OmnAPI Docs

Generate Producer lyrics

Guide

Use an API key with task:create; query the resulting Task with task:read. Set OMNAPI_KEY to your API key. Example media URLs must be replaced with your own reachable files. Complete the Producer quickstart for the full receipt-to-song workflow.

Save a fresh REQUEST_KEY once for this operation. Reuse the key and the exact body on an uncertain response; another operation needs its own saved key.

Terminal window
export REQUEST_KEY="$(uuidgen)"

Request

Section titled “Request”

Generates structured lyrics for downstream composition.

Example

Section titled “Example”

The prompt should describe theme + genre + language (e.g. “Bittersweet pop, English, about leaving a coastal town”).

Terminal window
curl -X POST https://api.omnapi.com/api/v1/producer/generate/lyrics \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Bittersweet coastal pop in English, with a memorable chorus"}'

Acceptance and recovery

Section titled “Acceptance and recovery”

Creation returns a Task receipt (HTTP 200). Save taskId, then poll GET /api/v1/tasks/{taskId} until COMPLETED, FAILED, or CANCELLED. A receipt is not the finished output. Stop on a terminal status and inspect retryable, refunded, and creditsCharged before starting another operation. If the response is lost, repeat the same request with the saved key.

See task recovery, pricing, and Producer editing and delivery.

Result shape

Section titled “Result shape”

This is an excerpt of the completed Task response (HTTP 200).

Lyrics are inline text resources; a separate text download URL is not required.

{
  "resources": [
    {
      "id": "resource_123",
      "type": "TEXT",
      "content": "[Verse]\nThe lighthouse blinks once for you...",
      "metadata": {
        "title": "Coastal Goodbye",
        "lyricsId": "lyrics_123"
      }
    }
  ]
}

Pass the chosen TEXT resource’s content to compose’s lyrics field. If using lyricsId, take it from that resource’s metadata, not from the Task ID.

Parameters

Section titled “Parameters”

Unknown fields are not accepted.

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

Field and typeRequirementDescription and constraints
promptstring Required Text prompt for lyrics generationMaximum characters: 3000.
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.