Przewodniki

Zadania asynchroniczne

Zlecaj długotrwałe zadania, odpytuj o status, obsługuj stany końcowe i pobieraj wyniki.

Niektóre operacje Felo natychmiast zwracają task_id i kończą się w tle. Wzorzec jest wszędzie taki sam: wyślij, odpytuj, a następnie pobierz wynik.

Dwie rodziny zadań

Rodzina	Wysyłanie	Odpytywanie
Przepływy Felo	`POST /v2/ppts`, `POST /v2/landing_page`, `POST /v2/mindmap`	`GET /v2/tasks/{task_id}/status`
Generowanie modeli	`POST /api/v1/videos/generations`, `POST /api/v1/images/generations`	`GET /api/v1/videos/generations/{task_id}`, `GET /api/v1/images/generations/{task_id}`

Eksport PPTX to osobna operacja asynchroniczna: POST /v2/ppts/{ppt_business_id}/export, a następnie GET /v2/ppts/{ppt_business_id}/export.

SuperAgent nie jest API do odpytywania. Zwraca stream_key i używa SSE; zobacz Dokumentacja SuperAgent.

Cykl życia

Wyślij. Wyślij parametry modelu lub przepływu pracy. Skuteczne wysłanie zwraca task_id i początkowy stan.
Odpytuj. Odczytuj endpoint zadania w regularnych odstępach. W kodzie ustal interwał i maksymalny czas oczekiwania.
Zakończ. Przy powodzeniu odczytaj adresy URL wyników lub pola wyjściowe. Przy niepowodzeniu odczytaj błąd i zdecyduj, czy wysłać zadanie ponownie.

Wartości stanu

Zadania przepływów Felo używają wartości wielkimi literami:

Stan	Znaczenie
`RUNNING`	Wciąż przetwarzane
`COMPLETED`	Zakończone powodzeniem
`FAILED`	Niepowodzenie terminalne; odczytaj `error_message`
`PENDING`	Stan terminalny w odpowiedzi historycznej; odczytaj `error_message`
`EXPIRED`	Stan terminalny; zadanie nie jest już dostępne
`CANCELED`	Stan terminalny; zadanie zostało anulowane

Zadania generowania modeli używają wartości małymi literami: queued, running, succeeded, failed i interrupted. Nieudane zadanie może zawierać obiekt error z polami message i type.

Wraz z rozwojem backendu mogą pojawiać się nieznane wartości stanu. Traktuj nieznaną wartość jako nieterminalną, chyba że dokumentacja mówi inaczej.

Odpytywanie

Zadania przepływów Felo: odpytuj co 2–5 sekund.
Generowanie wideo: odpytuj co 5–10 sekund.
Generowanie obrazów: zacznij od 2–5 sekund i zwiększaj odstępy dla długotrwałych zadań.
Zatrzymaj się przy stanie terminalnym, wybranym przez siebie limicie czasu lub po maksymalnej liczbie prób.
Dodaj losowe odchylenie, gdy wielu klientów odpytuje jednocześnie.

Prosta pętla w Node.js:

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

Pobieranie wyników

Zadanie	Wynik
PPT	`GET /v2/tasks/{task_id}/historical` zwraca `ppt_url`, `ppt_biz_id` i `live_doc_url`, gdy są dostępne
Strona docelowa	Odpowiedź historyczna zwraca wynik strony i `live_doc_url`, gdy jest dostępny
Wideo / obraz	Odpowiedź odpytania zwraca `outputs`; przy powodzeniu wpisy to podpisane adresy URL multimediów, które można pobrać anonimowo. Informacje o wygaśnięciu i pobieraniu znajdziesz w Generowaniu obrazów
Eksport PPTX	Odpowiedź odpytania zwraca `download_url` i `expires_at` tylko wtedy, gdy `status` ma wartość `COMPLETED`

Podpisany adres URL pobierania PPTX wygasa 30 minut po wydaniu. Wywołaj ponownie endpoint GET, aby uzyskać nowy adres URL; nie generuje to ponownie pliku.

Obsługa niepowodzeń

Przed ponowną próbą odczytaj pole błędu zadania. Niektóre niepowodzenia wynikają z żądania i będą się powtarzać.
Nie wysyłaj zadania ponownie na ślepo przy każdym przekroczeniu limitu czasu; najpierw sprawdź, czy zadanie nadal ma stan RUNNING.
402 oznacza niewystarczające kredyty. 429 oznacza limit szybkości. Ponów próbę dopiero po usunięciu przyczyny.
Pola wywołań zwrotnych przy generowaniu wideo i obrazów są obecnie ignorowane. Odpytuj endpoint zadania zamiast czekać na webhook.