Przewodniki

Szybki start

Tworzenie asynchronicznego zadania oraz obsługa odpytywania, ukończenia, niepowodzenia i wywołań zwrotnych.

RunAPI używa zadań (Tasks) do asynchronicznego generowania obrazów, wideo, dźwięku i muzyki. Żądanie tworzenia zwraca wynik szybko; Twoja aplikacja następnie sonduje zadanie lub odbiera zdarzenia wywołania zwrotnego wymienione w dokumentacji interfejsu API danego punktu końcowego.

Tworzenie zadania

Wybierz model i endpoint w Katalogu, a następnie wyślij wymagane dane wejściowe tego endpointu. Ten przykład uruchamia zadanie generowania obrazu z tekstu Flux 2:

SHELL

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'

Zaakceptowane żądanie asynchroniczne zwraca 202 Accepted z identyfikatorem zadania (Task):

JSON

{
  "id": "task_id",
  "status": "processing"
}

Przechowaj id razem z rekordem aplikacji. Jest to stabilny identyfikator używany do sondowania, obsługi technicznej i uzgadniania wywołań zwrotnych.

Zapobieganie duplikowaniu tworzonych zadań

Punkty końcowe tworzenia zadań przyjmują opcjonalny nagłówek Idempotency-Key z nieprzezroczystą wartością do 512 znaków. Wygeneruj jedną wartość dla każdego zadania logicznego i przechowuj ją wraz z żądaniem, dopóki nie wiesz, czy zostało przyjęte.

Jeśli przekroczenie limitu czasu lub awaria połączenia pozostawia wynik nieznany, ponów dokładnie to samo żądanie utworzenia zadania z tym samym kluczem. RunAPI zwraca oryginalne zadanie zamiast tworzyć i naliczać opłatę za drugie. Użycie klucza z innym żądaniem utworzenia zadania zwraca 409 Conflict. Wygeneruj nowy klucz dla celowo nowego zadania i nie używaj X-Client-Request-Id jako tego klucza.

Odtwórz przerwane żądanie synchroniczne

Powolne synchroniczne punkty końcowe zazwyczaj utrzymują połączenie otwarte i zwracają tę samą terminalową odpowiedź co dotychczas. Żadne zmiany sondowania nie są wymagane w istniejących integracjach.

Aby celowo skrócić budżet czasu połączenia, wyślij nagłówek Prefer: wait=N. Jeśli zadanie (Task) nadal działa po upływie tego jawnego budżetu, RunAPI zwraca 202 Accepted z tym samym id zadania, nieprzejrzystym adresem URL Location do odzyskania oraz Retry-After sugerującym opóźnienie kolejnego zapytania. Podążaj dokładnie za Location zamiast samodzielnie konstruować adres URL wyniku. Ukończony wynik zadania (Task Result) zachowuje terminalny status HTTP, dozwolone nagłówki, typ treści i treść; dekoduj response.body zgodnie z response.content_type, który nie zawsze jest JSON.

Odpytaj zadanie

Dołącz identyfikator zadania (Task) do tej samej ścieżki punktu końcowego:

SHELL

curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Kontynuuj, dopóki status ma wartość processing. Używaj ograniczonego wycofywania między żądaniami zamiast ciągłego odpytywania. Zadanie staje się końcowe, gdy jego status wynosi completed lub failed.

Obsługa ukończenia

Odpowiedź completed zawiera id zadania (Task), terminalny status oraz pola wynikowe specyficzne dla danego punktu końcowego. Zachowaj potrzebny wynik i zatrzymaj odpytywanie. Zapoznaj się z dokumentacją interfejsu API danego punktu końcowego, aby poznać dokładny kształt wyniku — nie zakładaj, że każdy punkt końcowy dla mediów zwraca te same pola.

Obsługa błędów

Odpowiedź failed zawiera id zadania (Task), terminalny status oraz autorski komunikat error RunAPI, jeśli jest dostępny. Zatrzymaj odpytywanie, zapisz identyfikator i błąd, a ponowną próbę podejmuj tylko wtedy, gdy aplikacja zakwalifikowała błąd jako przejściowy. Ponowna próba powoduje utworzenie nowego identyfikatora zadania (Task).

Odbierz wywołanie zwrotne

Dodaj publiczny adres HTTPS callback_url do żądania tworzenia, jeśli chcesz, aby RunAPI wysyłał zdarzenia wywołania zwrotnego opisane dla danego punktu końcowego:

JSON

{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}

Każde wywołanie zwrotne odpowiada jednemu zdarzeniu cyklu życia w dokumentacji API danego endpointu i pomija szczegóły rozliczeniowe dostępne wyłącznie przez odpytywanie. Terminalne wywołania zwrotne zawierają te same pola wynikowe co terminalne odpowiedzi odpytywania; niektóre endpointy wysyłają również udokumentowane wywołania zwrotne processing. Szybko zwróć pomyślną odpowiedź HTTP i utrzymuj dostępność odpytywania na potrzeby uzgadniania w przypadku opóźnionego dostarczenia lub niedostępności obsługi wywołań zwrotnych.

Przeczytaj artykuł Wywołania zwrotne, aby dowiedzieć się, jak utworzyć sekret wywołania zwrotnego, weryfikować podpisy i bezpiecznie obsługiwać ponowne próby.