Leitfäden

Asynchrone Aufgaben

Reichen Sie lang laufende Jobs ein, fragen Sie den Status ab, behandeln Sie Endzustände und rufen Sie Ergebnisse ab.

Einige Felo-Operationen geben sofort eine task_id zurück und werden im Hintergrund abgeschlossen. Das Muster ist überall gleich: senden, abfragen, dann das Ergebnis abrufen.

Zwei Aufgabenfamilien

Familie	Senden	Abfragen
Felo-Workflows	`POST /v2/ppts`, `POST /v2/landing_page`, `POST /v2/mindmap`	`GET /v2/tasks/{task_id}/status`
Modellgenerierung	`POST /api/v1/videos/generations`, `POST /api/v1/images/generations`	`GET /api/v1/videos/generations/{task_id}`, `GET /api/v1/images/generations/{task_id}`

Der PPTX-Export ist eine separate asynchrone Operation: POST /v2/ppts/{ppt_business_id}/export, dann GET /v2/ppts/{ppt_business_id}/export.

SuperAgent ist keine Polling-API. Er gibt einen stream_key zurück und verwendet SSE; siehe die SuperAgent-Referenz.

Lebenszyklus

Senden. Senden Sie die Modell- oder Workflow-Parameter. Ein erfolgreicher Versand gibt task_id und einen anfänglichen Status zurück.
Abfragen. Rufen Sie den Aufgaben-Endpoint in einem festen Intervall auf. Legen Sie das Intervall und eine maximale Wartezeit im Code fest.
Abschließen. Lesen Sie bei Erfolg die Ergebnis-URLs oder Ausgabefelder. Lesen Sie bei einem Fehler den Fehler und entscheiden Sie, ob Sie erneut senden.

Statuswerte

Aufgaben von Felo-Workflows verwenden Großbuchstaben:

Status	Bedeutung
`RUNNING`	Wird noch verarbeitet
`COMPLETED`	Erfolgreich abgeschlossen
`FAILED`	Endgültiger Fehler; lesen Sie `error_message`
`PENDING`	Endstatus in der historischen Antwort; lesen Sie `error_message`
`EXPIRED`	Endstatus; die Aufgabe ist nicht mehr verfügbar
`CANCELED`	Endstatus; die Aufgabe wurde abgebrochen

Aufgaben der Modellgenerierung verwenden Kleinbuchstaben: queued, running, succeeded, failed und interrupted. Eine fehlgeschlagene Aufgabe kann ein error-Objekt mit message und type enthalten.

Mit der Weiterentwicklung des Backends können unbekannte Statuswerte auftreten. Behandeln Sie einen unbekannten Wert als nicht terminal, sofern die Dokumentation nichts anderes angibt.

Abfragen

Aufgaben von Felo-Workflows: alle 2–5 Sekunden abfragen.
Videogenerierung: alle 5–10 Sekunden abfragen.
Bildgenerierung: mit 2–5 Sekunden beginnen und bei lang laufenden Aufgaben die Wartezeit erhöhen.
Beenden Sie bei einem Endstatus, bei einem von Ihnen gewählten Timeout oder nach einer maximalen Anzahl von Versuchen.
Fügen Sie Jitter hinzu, wenn viele Clients gleichzeitig abfragen.

Eine einfache Node.js-Schleife:

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

Ergebnisse abrufen

Aufgabe	Ergebnis
PPT	`GET /v2/tasks/{task_id}/historical` gibt `ppt_url`, `ppt_biz_id` und `live_doc_url` zurück, sofern verfügbar
Landing Page	Die historische Antwort gibt die Seitenausgabe und `live_doc_url` zurück, sofern verfügbar
Video / Bild	Die Abfrageantwort gibt `outputs` zurück; bei Erfolg sind die Einträge signierte Medien-URLs, die anonym heruntergeladen werden können. Details zu Ablauf und Download finden Sie unter Bildgenerierung
PPTX-Export	Die Abfrageantwort gibt `download_url` und `expires_at` nur zurück, wenn `status` den Wert `COMPLETED` hat

Die signierte Download-URL für PPTX läuft 30 Minuten nach Ausstellung ab. Rufen Sie den GET-Endpoint erneut auf, um eine frische URL zu erhalten; die Datei wird dabei nicht neu erzeugt.

Fehlerbehandlung

Lesen Sie das Fehlerfeld der Aufgabe, bevor Sie es erneut versuchen. Einige Fehler werden durch die Anfrage verursacht und treten erneut auf.
Senden Sie bei jedem Timeout nicht blind erneut; prüfen Sie zuerst, ob die Aufgabe noch RUNNING ist.
402 bedeutet unzureichendes Guthaben. 429 bedeutet ein Rate-Limit. Versuchen Sie es erst erneut, wenn die Bedingung behoben ist.
Callback-Felder bei Video- und Bildgenerierung werden derzeit ignoriert. Fragen Sie den Aufgaben-Endpoint ab, statt auf einen Webhook zu warten.