Zamówienia

Śledzenie zleceń generowania, odpytywanie o status oraz odczyt wyników poszczególnych zadań, w tym adresów plików i kategorii błędów.

Każde zlecenie generowania tworzy zamówienie. Zamówienie grupuje jedno lub więcej zadań — po jednym na generowany zasób. Te endpointy pozwalają śledzić tę pracę aż do zakończenia.

Oba wymagają scope'u content.read.

GET /api/external/orders

Lista ostatnich zamówień konta, od najnowszych. Bez rozbicia na zadania — od tego jest endpoint szczegółów.

Parametry zapytania

Parametr	Typ	Opis
`status`	string	Filtrowanie po statusie zamówienia.
`limit`	number	Ile zwrócić. Ograniczone do `[1, 50]`, domyślnie `20`.
`since`	string	Znacznik czasu ISO 8601; tylko zamówienia utworzone później.

Odpowiedź

{
  "orders": [
    {
      "orderId": "131a2aec-...",
      "status": "in_progress",
      "jobType": "video",
      "provider": "pollo",
      "model": "mixed",
      "jobsTotal": 2,
      "jobsCompleted": 1,
      "jobsFailed": 0,
      "createdAt": "2026-05-06T07:42:52.668Z",
      "updatedAt": "2026-05-06T07:43:18.016Z"
    }
  ],
  "limit": 20,
  "returned": 1
}

GET /api/external/orders/:id

Jedno zamówienie z pełnym rozbiciem na zadania.

Parametry ścieżki

Parametr	Typ	Opis
`id`	string	UUID zamówienia zwrócony przy jego utworzeniu.

Odpowiedź

{
  "orderId": "131a2aec-...",
  "status": "completed",
  "jobType": "video",
  "provider": "pollo",
  "model": "mixed",
  "jobsTotal": 2,
  "jobsCompleted": 2,
  "jobsFailed": 0,
  "createdAt": "...",
  "updatedAt": "...",
  "jobs": [
    {
      "jobId": "...",
      "provider": "pollo",
      "model": "kling-2.6",
      "status": "completed",
      "attemptCount": 2,
      "outputUrl": "https://storage.../video.mp4",
      "errorCategory": null,
      "errorHint": null,
      "startedAt": "...",
      "completedAt": "..."
    }
  ]
}

Pola zadania

Pole	Opis
`status`	`pending`, `in_progress`, `completed`, `failed`, `retry_pending`, `cancelled`, `expired`.
`attemptCount`	Ile razy zadanie było uruchamiane. Wartość powyżej 1 oznacza ponowienie.
`outputUrl`	Wygenerowany zasób. Wypełniony tylko dla zadań `completed`, w pozostałych `null`.
`errorCategory`	Dlaczego zadanie się nie powiodło — zobacz Kategorie niepowodzeń zadań. `null`, jeśli zadanie nie zawiodło.
`errorHint`	Jedno zdanie wyjaśniające kategorię. Wyświetl je człowiekowi, nie parsuj.

Odpytywanie o status

Zamówienia kończą się asynchronicznie. Odpytuj endpoint szczegółów, dopóki status nie będzie completed, failed lub cancelled.

Dwie rzeczy warte uwagi, zanim napiszesz pętlę:

Nieudane zadanie nie zawsze jest ostateczne. TRANSIENT_INFRA, RATE_LIMIT i PROVIDER_CAPACITY są ponawiane automatycznie, więc zadanie może zgłosić jedną z tych kategorii i mimo to zakończyć się powodzeniem przy kolejnej próbie. Patrz na status i attemptCount, nie na samą obecność errorCategory.

Częściowe ukończenie jest normalne. Zamówienie z wieloma zadaniami może zakończyć się tak, że część jest completed, a część failed. Czytaj jobsCompleted i jobsFailed zamiast zakładać, że zamówienie jest „wszystko albo nic".

Pamiętaj o limicie 60 zapytań na minutę — zobacz Limity zapytań. Odpytywanie co kilka sekund na zamówienie w zupełności wystarcza; generowanie trwa znacznie dłużej.

Błędy

Kod	Przyczyna
`400`	`id` nie jest poprawnym UUID albo parametr zapytania jest nieprawidłowy.
`401`	Brak klucza API, klucz nieprawidłowy lub odwołany.
`403`	Klucz nie ma scope'u `content.read`.
`404`	Zamówienie nie istnieje albo należy do innego konta. Te przypadki są świadomie nierozróżnialne.
`429`	Przekroczony limit zapytań.