OmnAPI Quickstart

This page walks you from zero to a finished song. The create endpoints follow the same contract: send a JSON body, receive a task descriptor, then poll GET /api/v1/tasks/{taskId} until status is terminal.

Tip

If you’d rather click than type, jump straight to the Interactive Reference, enter an API key for your own browser session, and run real requests.

0. Get a key

Sign in to the OmnAPI dashboard, go to Settings → API Keys, and create one. Store it as OMNAPI_KEY in your environment or secret manager; do not hard-code API keys in source files.

export OMNAPI_KEY="sk_live_..."

See Authentication for rotation and security details.

---

1. Generate an image

The simplest POST in the catalog — one required field.

curl

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

TypeScript

const res = await fetch(
  "https://api.omnapi.com/api/v1/producer/generate/image",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.OMNAPI_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "synthwave album cover, neon palms, retro grid horizon",
    }),
  },
);
const task = await res.json();

Python

import os, requests

r = requests.post(
    "https://api.omnapi.com/api/v1/producer/generate/image",
    headers={"x-api-key": os.environ["OMNAPI_KEY"]},
    json={"prompt": "synthwave album cover, neon palms, retro grid horizon"},
)
task = r.json()

Response — note the taskId and the required credit count:

{
  "taskId": "task_01H...",
  "status": "PENDING",
  "creditsRequired": 8,
  "createdAt": "2026-05-23T10:00:00Z"
}

---

2. Generate lyrics

curl -X POST https://api.omnapi.com/api/v1/producer/generate/lyrics \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Bittersweet pop song about leaving a coastal town at dawn. English."
  }'

The prompt field accepts up to 3000 characters. The task returns lyrics with structure tags ([Verse], [Chorus], [Bridge]) that can be passed into music compose.

---

3. Compose a full song

The only required field is soundPrompt — the sonic description. Everything else is optional but useful. When instrumental is omitted or false and you do not provide lyrics, OmnAPI can generate lyrics first so the final song includes a vocal-ready lyric plan.

Minimal

curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/compose \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "soundPrompt": "lofi jazz, rainy night, soft piano"
  }'

With lyrics + tuning

curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/compose \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "soundPrompt": "lofi jazz, rainy night, soft piano",
    "lyrics": "[Verse]\nQuiet streets keep their secrets...",
    "title": "Wet Pavement",
    "instrumental": false,
    "bpm": 78,
    "length": 90
  }'

Instrumental only

curl -X POST https://api.omnapi.com/api/v1/producer/generate/music/compose \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "soundPrompt": "tense cinematic build, low strings, sparse percussion",
    "instrumental": true,
    "length": 60
  }'

Field cheat sheet (full reference: Producer API):

Field	Required	Limit	Notes
soundPrompt	✅	≤ 500 chars	The sonic description
lyrics	—	≤ 3000 chars	Use structure tags from the lyrics endpoint
instrumental	—	bool	Default false
bpm	—	1–300	Tempo hint
length	—	1–600 sec	Target duration
title	—	≤ 200 chars	Cosmetic
seed	—	≥ 0	Reproducibility

---

4. Poll the task

The same task polling endpoint works for image, lyrics, and music tasks — they all share one task model.

curl https://api.omnapi.com/api/v1/tasks/$TASK_ID \
  -H "x-api-key: $OMNAPI_KEY"

Status progresses PENDING → PROCESSING → COMPLETED (or FAILED / CANCELLED). Poll with exponential backoff — see The Task Model for the exact schedule, why aggressive polling is discouraged, and how to read the result.

When status: "COMPLETED", you’ll get:

{
  "taskId": "task_01H...",
  "status": "COMPLETED",
  "creditsRequired": 28,
  "creditsCharged": 28,
  "resources": [
    { "type": "audio", "url": "https://cdn.omnapi.com/..." }
  ],
  "outputResults": { /* endpoint-specific details */ }
}

creditsCharged may be lower than creditsRequired for partial-billing scenarios (see Credits & Billing). On most FAILED tasks, eligible credits are refunded automatically; partial-output cases may keep a smaller final charge.

Where to go next

• The Task Model — the shared contract: lifecycle, config, polling, sync/async
• Producer API — every field of every endpoint explained
• Errors — error code reference + retry guidance