Your First OmnAPI Task

Start with one image task. The same create → receipt → result pattern applies to music and video. For a complete program with persisted recovery state, use the Python and TypeScript examples.

1. Prepare a key and one request

Create an API key in Dashboard → API Keys. This walkthrough uses an image operation priced at 8 standard credits before customer pricing. Check your balance and pricing first.

export OMNAPI_KEY="your-server-side-key"
# Generate once for this logical job. Save it; retries must use this same value.
export IDEMPOTENCY_KEY="$(uuidgen)"

Keep the API key on your server. If the network fails, retain this request’s key and body; generating another key would identify a new paid operation.

2. Create the task

curl --fail-with-body -X POST https://api.omnapi.com/api/v1/producer/generate/image \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"synthwave album cover, neon palms, retro grid horizon"}'

Save taskId from the response. A receipt is acceptance, not completion:

{
  "taskId": "task_123",
  "status": "PENDING",
  "creditsRequired": 8
}

This is a minimal response excerpt. The full response also includes product, links and pricing fields; see Task Model.

3. Read the result

Set TASK_ID to the actual receipt value, then query with capped backoff:

export TASK_ID="task_123"
curl --fail-with-body "https://api.omnapi.com/api/v1/tasks/$TASK_ID" \
  -H "x-api-key: $OMNAPI_KEY"

Status	Next step
PENDING / PROCESSING	Wait and poll again; respect Retry-After
COMPLETED	Read the selected resource’s URL or content
FAILED / CANCELLED	Stop polling; inspect errorCode, retryable, refunded and creditsCharged

A completed image task includes a resource like this:

{
  "status": "COMPLETED",
  "resources": [
    {
      "id": "image_123",
      "type": "IMAGE",
      "url": "https://media.example.com/cover.png"
    }
  ]
}

Types are uppercase. A Producer song uses MUSIC; lyrics use TEXT with inline content. Download the returned URL without sending your API key to the media host, and preserve needed output before its retention deadline.

Use the bounded polling helper in an application. For a missing receipt after a timeout, recover the original request with the same route, body and idempotency key. A 4xx/5xx response can include an already created task ID; inspect it before retrying.

Choose your next workflow

• Producer song — compose and consume a MUSIC resource.
• Suno song — follow candidates and play audio during generation.
• Music video — quote, validate, create and download.
• SDK setup — install the provided TypeScript or Python client.