Asynchronous tasks

MoonNexAI video, music, digital human and some image APIs run as asynchronous tasks. Save task_id after creation, then poll the status or wait for a webhook.

Create a task

curl https://moonnexai.com/v1/tasks \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-music-v5.5",
    "prompt": "A warm pop song about sunrise.",
    "title": "Morning Light"
  }'

Query a task

curl https://moonnexai.com/v1/tasks/task_xxx \
  -H "Authorization: Bearer <MOONNEXAI_API_KEY>"

Handle status

Status	Meaning
pending / submitted	Created or submitted.
running	Processing.
succeeded	Completed; the result can be read.
failed	Failed; inspect fail_reason or error.
cancelled	Cancelled.

Some models return uppercase states such as SUBMITTED, QUEUED, IN_PROGRESS, SUCCESS and FAILURE. Your application can normalize equivalent states.

Recommendations

• Always save the task_id from the creation response.
• Check status and error before reading a media URL on the frontend or server. A URL alone does not establish success.
• Failed tasks usually include a safe fail_reason that can be shown to the user.
• Use webhooks for long tasks where supported and retain polling.

Common endpoints

Capability	Create	Query
Music	POST /v1/tasks	GET /v1/tasks/{task_id}
Digital human audio	POST /v1/tasks	GET /v1/tasks/{task_id}
Digital human video	POST /v1/tasks	GET /v1/tasks/{task_id}
Video	POST /v1/videos	GET /v1/videos/{task_id}
Asynchronous images	POST /v1/images/generations/async	GET /v1/images/tasks/{task_id}