Felo API PlatformFelo API Platform

Kılavuzlar

Eşzamansız görevler

Uzun süren işleri gönderin, durumu sorgulayın, son durumları yönetin ve sonuçları alın.

Bazı Felo işlemleri hemen bir task_id döndürür ve arka planda tamamlanır. Desen her yerde aynıdır: gönderin, yoklayın, ardından sonucu alın.

İki görev ailesi

AileGöndermeYoklama
Felo iş akışlarıPOST /v2/ppts, POST /v2/landing_page, POST /v2/mindmapGET /v2/tasks/{task_id}/status
Model oluşturmaPOST /api/v1/videos/generations, POST /api/v1/images/generationsGET /api/v1/videos/generations/{task_id}, GET /api/v1/images/generations/{task_id}

PPTX dışa aktarma ayrı bir eşzamansız işlemdir: POST /v2/ppts/{ppt_business_id}/export, ardından GET /v2/ppts/{ppt_business_id}/export.

SuperAgent bir yoklama API'si değildir. Bir stream_key döndürür ve SSE kullanır; bkz. SuperAgent referansı.

Yaşam döngüsü

  1. Gönderin. Model veya iş akışı parametrelerini iletin. Başarılı bir gönderim task_id ve bir başlangıç durumu döndürür.
  2. Yoklayın. Görev endpoint'ini bir aralıkla okuyun. Aralığı ve maksimum bekleme süresini kodunuzda tutun.
  3. Tamamlayın. Başarı durumunda sonuç URL'lerini veya çıktı alanlarını okuyun. Arıza durumunda hatayı okuyun ve yeniden gönderip göndermeyeceğinize karar verin.

Durum değerleri

Felo iş akışı görevleri büyük harfli değerler kullanır:

DurumAnlamı
RUNNINGHâlâ işleniyor
COMPLETEDBaşarıyla tamamlandı
FAILEDNihai arıza; error_message alanını okuyun
PENDINGGeçmiş yanıtında nihai; error_message alanını okuyun
EXPIREDNihai; görev artık kullanılamıyor
CANCELEDNihai; görev iptal edildi

Model oluşturma görevleri küçük harfli değerler kullanır: queued, running, succeeded, failed ve interrupted. Başarısız bir görev, message ve type içeren bir error nesnesi içerebilir.

Arka uç geliştikçe bilinmeyen durum değerleri görünebilir. Belgeler aksini söylemediği sürece bilinmeyen bir değeri nihai olmayan olarak değerlendirin.

Yoklama

  • Felo iş akışı görevleri: her 2–5 saniyede bir yoklayın.
  • Video oluşturma: her 5–10 saniyede bir yoklayın.
  • Görsel oluşturma: 2–5 saniyeyle başlayın ve uzun süren görevler için geri çekilin.
  • Nihai bir durumda, seçtiğiniz bir zaman aşımında veya maksimum deneme sayısından sonra durun.
  • Birçok istemci aynı anda yokladığında titreşim ekleyin.

Basit bir Node.js döngüsü:

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");
}

Sonuçları alma

GörevSonuç
PPTGET /v2/tasks/{task_id}/historical, mevcut olduğunda ppt_url, ppt_biz_id ve live_doc_url döndürür
Açılış sayfasıGeçmiş yanıtı, mevcut olduğunda sayfa çıktısını ve live_doc_url döndürür
Video / görselYoklama yanıtı outputs döndürür; başarılı olduğunda girdiler anonim olarak indirilebilen imzalı medya URL'leridir. Son kullanma ve indirme ayrıntıları için bkz. Görsel Oluşturma
PPTX dışa aktarmaYoklama yanıtı download_url ve expires_at alanlarını yalnızca status değeri COMPLETED olduğunda döndürür

PPTX imzalı indirme URL'sinin süresi düzenlendikten 30 dakika sonra dolar. Yeni bir URL için GET endpoint'ini yeniden çağırın; bu dosyayı yeniden oluşturmaz.

Hata yönetimi

  • Yeniden denemeden önce görevin hata alanını okuyun. Bazı arızalar istekten kaynaklanır ve tekrarlanır.
  • Her zaman aşımında körü körüne yeniden göndermeyin; önce görevin hâlâ RUNNING olup olmadığını kontrol edin.
  • 402 yetersiz kredi anlamına gelir. 429 bir hız sınırı anlamına gelir. Yalnızca koşul çözüldükten sonra yeniden deneyin.
  • Video ve görsel oluşturmadaki geri çağırma alanları şu anda yok sayılır. Webhook beklemek yerine görev endpoint'ini yoklayın.

İlgili