First API Request

Create your first OmnAPI task

Generate a cover image with one prompt, save the task ID, and retrieve the result. The same create-and-track pattern is used across the music and video products.

1. Prepare a server-side API key

Create an account, open API keys in the dashboard, and confirm your credit balance. These examples use a shell with cURL and uuidgen. Keep the real key out of browser code, source control, and shared terminal history.

export OMNAPI_KEY="YOUR_API_KEY"
# Generate once. Keep this value when retrying the same request.
export REQUEST_ID="$(uuidgen)"

In production, inject OMNAPI_KEY from your secret manager. Generate a new REQUEST_ID for each new user action and keep it for retries of that action.

2. Create a cover image

This request creates real paid work if you run it with a funded account. Check current pricing before submitting. The required input is prompt; image prompts allow up to 2,000 characters.

curl --fail-with-body --max-time 60 -X POST "https://api.omnapi.com/api/v1/producer/generate/image" \
  -H "x-api-key: $OMNAPI_KEY" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -H "Content-Type: application/json" \
  --data '{
  "prompt": "Abstract synthwave album artwork, neon palms, deep blue background, no text"
}'

Illustrative response excerpt below; the actual task ID, initial state, and credit fields come from your response. Acceptance is not completion.

{
  "taskId": "YOUR_RETURNED_TASK_ID",
  "status": "PENDING"
}

3. Read the task status

Save the returned taskId before responding to your frontend. Set TASK_ID to that value and read the Task API:

export TASK_ID="YOUR_RETURNED_TASK_ID"

curl --fail-with-body --max-time 30 \
  "https://api.omnapi.com/api/v1/tasks/$TASK_ID" \
  -H "x-api-key: $OMNAPI_KEY"
  • COMPLETED: inspect the returned resources and save the files your application needs.
  • FAILED or CANCELLED: stop polling and show the task error or cancellation state.
  • Other states: wait before checking again. Use a bounded polling window and backoff; keep taskId so you can resume later without creating another task.

An HTTP timeout in your client does not cancel the generation. A production backend can also receive signed webhook events.

4. Handle errors and keep the result

  • For authentication or validation errors, correct the key or payload before retrying. Never log the key.
  • For HTTP 429, honor Retry-After when supplied and use backoff. Do not create a burst of replacement tasks.
  • On an uncertain create response, retry the same request with the same idempotency key instead of starting a new paid job.
  • Review generated artwork before publishing and copy approved files into storage you control before their delivery links expire.

Public source: OmnAPI quickstart. For model-specific fields and output details, use the linked product reference.