Task lifecycle

A generation task moves through four public statuses:

POST /generation-tasks returns the task immediately, usually as running. The work happens in the background.

Reading a task

curl https://api.mageran.ai/api/v1/generation-tasks/cmagr01hxyz123 \
  --header 'x-mager-api-key: YOUR_API_KEY'

The response carries everything about the task:

{
  "task_id": "cmagr01hxyz123",
  "status": "finished",
  "model": "image-generator",
  "template_id": null,
  "callback_url": "https://client.example.com/webhooks/mager",
  "created_at": "2026-07-03T06:00:00.000Z",
  "completed_at": "2026-07-03T06:01:00.000Z",
  "error": null,
  "billing": { "base_moods": 10, "charged_moods": 15, "extra_moods_charged": 5 },
  "result": [
    {
      "id": "result_01hxyz",
      "status": "SUCCESS",
      "file_url": "https://cdn.example.com/generated-image.png",
      "file_type": "image/png",
      "external_task_id": "provider_task_01hxyz"
    }
  ],
  "webhooks": [{ "id": "delivery_01hxyz", "status": "PENDING", "attempts": 0, "max_attempts": 3 }]
}

result is empty until the task finishes. output_count on the request decides how many entries land there.

Polling

If you are not using webhooks:

• Poll every 3–5 seconds. Faster does not make generation faster, and it burns your rate limit.
• Stop when status is finished or failed. Those are terminal; the task will not change again.
• Give up after a ceiling you choose — a minute or two of no movement usually means something is wrong upstream, and you want to surface that to your user rather than spin.

A task that stays queued is waiting for capacity, not stuck. A task that stays running past your ceiling is worth reporting.

Downloading results

file_url points at a CDN object. Download it and store it yourself if you need it long-term — treat the URL as a handle for fetching, not as permanent storage for your application.

Prefer webhooks

Polling is the fallback. Pass a callback_url when you create the task and Mager calls you once the task reaches finished or failed. See Webhooks.