Panduan

Tugas asinkron

Kirim tugas berdurasi panjang, pantau status, tangani status akhir, dan ambil hasil.

Beberapa operasi Felo langsung mengembalikan task_id dan selesai di latar belakang. Polanya sama di semua tempat: kirim, polling, lalu ambil hasilnya.

Dua keluarga tugas

Keluarga	Kirim	Polling
Alur kerja Felo	`POST /v2/ppts`, `POST /v2/landing_page`, `POST /v2/mindmap`	`GET /v2/tasks/{task_id}/status`
Generasi model	`POST /api/v1/videos/generations`, `POST /api/v1/images/generations`	`GET /api/v1/videos/generations/{task_id}`, `GET /api/v1/images/generations/{task_id}`

Ekspor PPTX adalah operasi asinkron terpisah: POST /v2/ppts/{ppt_business_id}/export, lalu GET /v2/ppts/{ppt_business_id}/export.

SuperAgent bukan API polling. SuperAgent mengembalikan stream_key dan menggunakan SSE; lihat referensi SuperAgent.

Siklus Hidup

Kirim. Kirim parameter model atau alur kerja. Pengiriman yang berhasil mengembalikan task_id dan status awal.
Polling. Baca endpoint tugas secara berkala. Tetapkan interval dan waktu tunggu maksimum di kode Anda.
Selesai. Saat berhasil, baca URL hasil atau field output. Saat gagal, baca error dan putuskan apakah akan mengirim ulang.

Nilai Status

Tugas alur kerja Felo menggunakan nilai huruf besar:

Status	Arti
`RUNNING`	Masih diproses
`COMPLETED`	Selesai dengan berhasil
`FAILED`	Kegagalan terminal; baca `error_message`
`PENDING`	Terminal dalam respons historis; baca `error_message`
`EXPIRED`	Terminal; tugas tidak lagi tersedia
`CANCELED`	Terminal; tugas dibatalkan

Tugas generasi model menggunakan nilai huruf kecil: queued, running, succeeded, failed, dan interrupted. Tugas yang gagal dapat menyertakan objek error dengan message dan type.

Nilai status yang tidak dikenal dapat muncul seiring perkembangan backend. Perlakukan nilai yang tidak dikenal sebagai non-terminal kecuali dokumentasi menyatakan sebaliknya.

Polling

Tugas alur kerja Felo: polling setiap 2–5 detik.
Generasi video: polling setiap 5–10 detik.
Generasi gambar: mulai dengan 2–5 detik dan lakukan backoff untuk tugas yang berjalan lama.
Berhenti pada status terminal, pada batas waktu yang Anda tentukan, atau setelah jumlah percobaan maksimum.
Tambahkan jitter saat banyak klien melakukan polling secara bersamaan.

Perulangan Node.js sederhana:

async function pollStatus(taskId, { timeoutMs = 10 * 60 * 1000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const response = await fetch(`https://openapi.felo.ai/v2/tasks/${taskId}/status`, {
      headers: { Authorization: `Bearer ${process.env.FELO_API_KEY}` },
    });
    if (!response.ok) throw new Error(`status ${response.status}`);
    const payload = await response.json();
    const status = payload.data?.status;
    if (status === "COMPLETED") return payload.data;
    if (["FAILED", "PENDING", "EXPIRED", "CANCELED"].includes(status)) {
      throw new Error(payload.data?.error_message || status);
    }
    await new Promise((resolve) => setTimeout(resolve, 3000));
  }
  throw new Error("task timed out");
}

Mengambil Hasil

Tugas	Hasil
PPT	`GET /v2/tasks/{task_id}/historical` mengembalikan `ppt_url`, `ppt_biz_id`, dan `live_doc_url` jika tersedia
Landing page	Respons historis mengembalikan output halaman dan `live_doc_url` jika tersedia
Video / gambar	Respons polling mengembalikan `outputs`; saat berhasil, entri berupa URL media bertanda tangan yang dapat diunduh secara anonim. Lihat Generasi Gambar untuk detail kedaluwarsa dan unduhan
Ekspor PPTX	Respons polling mengembalikan `download_url` dan `expires_at` hanya saat `status` bernilai `COMPLETED`

URL unduhan bertanda tangan PPTX kedaluwarsa 30 menit setelah diterbitkan. Panggil endpoint GET lagi untuk mendapatkan URL baru; ini tidak meregenerasi file.

Penanganan Kegagalan

Baca field error tugas sebelum mencoba ulang. Sebagian kegagalan disebabkan oleh permintaan dan akan berulang.
Jangan mengirim ulang secara membabi buta pada setiap batas waktu; periksa dulu apakah tugas masih RUNNING.
402 berarti kredit tidak mencukupi. 429 berarti batas laju. Lakukan percobaan ulang hanya setelah kondisi tersebut teratasi.
Field callback pada generasi video dan gambar saat ini diabaikan. Lakukan polling endpoint tugas alih-alih menunggu webhook.