Task lifecycle

Sebuah generation task melewati empat status publik:

POST /generation-tasks mengembalikan task-nya seketika, biasanya sebagai running. Pekerjaannya berjalan di latar belakang.

Membaca sebuah task

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

Response-nya membawa semua hal tentang task tersebut:

{
  "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 kosong sampai task selesai. output_count pada permintaan menentukan berapa banyak entri yang muncul di sana.

Polling

Kalau Anda tidak memakai webhook:

• Polling tiap 3–5 detik. Lebih cepat tidak membuat generasi lebih cepat, dan itu menghabiskan rate limit Anda.
• Berhenti saat status bernilai finished atau failed. Keduanya final; task tidak akan berubah lagi.
• Menyerahlah setelah batas yang Anda tentukan sendiri — satu atau dua menit tanpa pergerakan biasanya berarti ada masalah di hulu, dan itu lebih baik disampaikan ke pengguna daripada dibiarkan berputar.

Task yang bertahan di queued sedang menunggu kapasitas, bukan macet. Task yang bertahan di running melewati batas Anda layak dilaporkan.

Mengunduh hasil

file_url menunjuk ke objek di CDN. Unduh dan simpan sendiri kalau Anda membutuhkannya untuk jangka panjang — perlakukan URL itu sebagai sarana pengambilan, bukan penyimpanan permanen untuk aplikasi Anda.

Lebih baik pakai webhook

Polling adalah cadangan. Kirim callback_url saat membuat task dan Mager akan menghubungi Anda begitu task mencapai finished atau failed. Lihat Webhooks.