Task lifecycle and results

A task is a generation job. Save its taskId, poll GET /api/v1/tasks/{taskId}, and use the output when it completes.

Status	What to do
`PENDING` or `PROCESSING`	Wait and poll again with backoff.
`COMPLETED`	Read the product result or the task’s `resources`.
`FAILED` or `CANCELLED`	Stop polling. Inspect the error and final credit charge.

Receipts differ by product: Suno also returns a Generation for song candidates; Music Video returns an MV ID for scenes and the final video. Follow the product’s quickstart for its response shape. First task.

Producer generation is currently paused. Dedicated Producer endpoints return 503 SERVICE_UNAVAILABLE, and generic Task creation rejects new Producer work before billing. Existing records and recovery for accepted tasks are retained. Producer availability.

The request `config`

The generic Task API and products such as Suno accept config for shared job settings. Check the operation schema before copying it: Audio Editing, for example, accepts webhookUrl at the top level.

{
  "config": {
    "priority": 5,
    "tags": [
      "alpha",
      "experiment-7"
    ],
    "metadata": {
      "orderId": "ord_123",
      "source": "my-app"
    },
    "webhookUrl": "https://yourapp.com/callbacks/omnapi"
  }
}

Field	Type	Notes
`priority`	int	`1`–`10`, default `5`. Higher runs sooner under contention.
`tags`	string[]	Up to 20 free-form labels, echoed back on read.
`metadata`	object	Free-form JSON, echoed back on read. Your own correlation data.
`webhookUrl`	string (URL)	Receive `task.*` events for this task. See Webhook Events.

Running a task: async (default) vs sync

Async (the default)

Product create endpoints return a receipt in a non-terminal state. MV returns immediately. Suno song and derive endpoints may wait briefly for provider acknowledgement so their product receipt can include real clipIds; send Prefer: respond-async to skip that wait. Poll the returned taskId until it reaches a terminal execution state:

{
  "taskId": "task_01H...",
  "status": "PENDING",
  "creditsRequired": 8
}

Suno song delivery has an additional product view at GET /api/v1/suno/generations/{generationId}. Use it for per-clip submitted | queued | streaming | complete | error states and early playable URLs in clips[].playback.url; use the Task descriptor for execution and billing. Live playback does not require an SSE subscription or a separate playback-session request. See Suno playback.

Generic task creation

Most integrations should use the product endpoints because they give clearer request fields. POST /api/v1/tasks is available when you want to submit by model path directly:

{
  "model": "suno/chirp-hawk/text-to-music",
  "inputParameters": {
    "prompt": "synthwave album cover, neon palms"
  },
  "priority": 5,
  "metadata": {
    "orderId": "ord_123"
  }
}

Generic task creation keeps task config fields flat at the top level: priority, tags, metadata, and webhookUrl. Do not send a top-level config wrapper on /api/v1/tasks; module endpoints use config because their own generation fields already occupy the top level.

The API Reference publishes model as a closed enum and shows the exact inputParameters schema for each feature branch. Vidu Direct, Subtitle Sync, and Audio Editing are available only through /api/v1/vidu/*, /api/v1/subtitles/*, and /api/v1/audio/renders, respectively; their model paths are not accepted here. For MV, only the unified managed-create model is accepted generically. If a product guide and a generic feature appear to overlap, prefer the product endpoint because its request and product response are the stable customer contract.

Sync (block for the result)

Where a short blocking call is useful, use POST /api/v1/tasks/sync with the same body shape as POST /api/v1/tasks. A sync call waits up to the server-side timeout and then:

completes in time → 200 with the full terminal descriptor (resources / outputResults populated).
times out → 202 with status: "PROCESSING" and a structured pollUrl. The task is not failed — it’s still running; keep polling pollUrl (which is /api/v1/tasks/{taskId}).

Example: HTTP 202 Accepted, with the task still running.

{
  "taskId": "task_01H...",
  "status": "PROCESSING",
  "pollUrl": "/api/v1/tasks/task_01H...",
  "creditsRequired": 12
}

Omn V1 preparation failures

Omn V1 may repair its generated reference images or planning text before video generation. These internal repairs do not add customer charges. MV_NATIVE_PREPARATION_REPAIR_EXHAUSTED means consistent materials could not be prepared within the repair limit. MV_NATIVE_PREPARATION_REPAIR_UNCERTAIN means a prior internal image purchase could not be confirmed safely, so the same purchase will not be repeated. Confirmed materials are reused during bounded recovery. If the task ends as failed, you may create a new request with a new Idempotency-Key. Both are service preparation failures, not a requirement to upload a portrait. Read the task’s settlement information for the actual credit outcome.

MV_NATIVE_REFERENCE_INPUT_REQUIRED applies to an explicitly supplied character image whose identity cannot be recognized reliably. Supply a clearer image for that character. It does not apply merely because an optional portrait is absent.

Status lifecycle

PENDING ──► PROCESSING ──► COMPLETED
                      │
                      ├──► FAILED
                      │
                      └──► CANCELLED

Terminal states are COMPLETED, FAILED, CANCELLED — stop polling once you hit one. The enum is uppercase and identical across every endpoint and webhook payload.

State	Meaning
`PENDING`	Queued for processing.
`PROCESSING`	Generation in progress (also the sync-timeout state).
`COMPLETED`	Done — `resources` and `outputResults` are populated.
`FAILED`	Generation or validation error — `errorCode` + `errorMessage` populated; eligible credits refunded unless partial output was billable.
`CANCELLED`	Cancelled before completion; eligible credits refunded.

For music videos, completion and creative approval are separate. The optional quality object in GET /api/v1/tasks/{taskId}/workflow describes sampled findings for that operation; it does not alter the Task state or settlement. Follow the finished-video review guidance before accepting the creative result or purchasing scene revisions.

MV quality findings labelled insufficient_evidence require manual inspection; they are excluded from confirmed sampled issue counts and suggested repairs. They do not alter the Task’s technical completion or credit settlement.

Task descriptor & `resources`

GET /api/v1/tasks/{taskId} returns the canonical descriptor:

{
  "taskId": "task_01H...",
  "status": "COMPLETED",
  "inputParameters": {
    "prompt": "..."
  },
  "creditsRequired": 8,
  "creditsCharged": 8,
  "refunded": false,
  "retryable": false,
  "warningCodes": [],
  "resources": [
    {
      "id": "res_01H...",
      "type": "IMAGE",
      "url": "https://cdn.omnapi.com/...",
      "contentType": "image/png"
    }
  ],
  "outputResults": {},
  "errorCode": null,
  "errorMessage": null,
  "createdAt": "2026-05-23T10:00:00Z",
  "updatedAt": "2026-05-23T10:00:18Z"
}

resources is the normalized, cross-module output array (id, type, plus operation-specific url, content, thumbnailUrl, or metadata). Prefer it when wiring downstream code. Types are uppercase: MUSIC, IMAGE, VIDEO, AUDIO, TEXT, METADATA. Songs can be MUSIC; text is in content. Do not require a URL for text or metadata.
outputResults carries endpoint-specific details — treat it as informational.
inputParameters can echo request inputs for debugging and audit trails; avoid sending secrets or sensitive personal data in task requests.
creditsRequired is deducted when the task is created.
creditsCharged is the final billed amount after completion, failure, cancellation, or partial output handling; see Credits & Billing.
refunded is a refund indicator, not a complete refund ledger. A successful Omn video with a subtitle partial refund can still report false; use the settled operation amounts for accounting. retryable is the service’s terminal retry recommendation.
warningCodes lists non-fatal warnings; see Warning codes.
Signed resources may include urlExpiresAt, retainedUntil, and assetStatus. Refresh the task to renew a URL and copy durable assets before retainedUntil. urlExpiresAt will never be later than retainedUntil.
Provider-account ids, tokens, viewer controls, and raw provider job ids are not part of the public task contract.

For the exhaustive field shapes of every public request and response, use the Interactive API Reference.

Warning codes

warningCodes flags inputs that were adjusted, degraded or recovered automatically. A warning does not by itself fail the Task. Match on the code, not on any message, and ignore codes you do not recognize. Each product guide lists its own codes.

Omn V1 workflow responses also expose an optional warningCodes array with up to 16 distinct codes. A successful video can carry a subtitle-delivery warning; see subtitle delivery and refunds.

For Omn V1 music videos, MV_NATIVE_PROMPT_COMPILATION_FALLBACK means that some shots were rendered from their original scene direction because the detailed shot prompts could not be prepared; the video is still delivered. Tasks that previously reported this condition as MV_NATIVE_CONTEXT_IR_FALLBACK now report MV_NATIVE_PROMPT_COMPILATION_FALLBACK; update any client that matches the earlier code. Omn V1 music videos created from 9 October 2026 render every shot from its scene direction and no longer report this code; it remains on earlier Tasks.

MV_NATIVE_CREATIVE_REVISION_RECOMMENDED means the finished Omn V1 composition has review findings that suggest revisions. MV_NATIVE_CREATIVE_REVIEW_REQUIRED means it needs manual review. These advisory codes appear on the Task result and MV view without withholding delivery or changing the price. Inspect the workflow quality summary and watch the video before buying a scene edit.

Continue the integration

Poll, stream, or cancel — Read existing work and respond to terminal states.
Recover an uncertain request — Reuse a saved key and know when a new attempt is appropriate.