Замовлення

Відстеження замовлень на генерацію, опитування їхнього статусу та читання результатів окремих завдань, включно з адресами файлів і категоріями помилок.

Кожен запит на генерацію створює замовлення. Замовлення об'єднує одне або кілька завдань — по одному на кожен ресурс, що генерується. Ці ендпоінти дозволяють стежити за цією роботою до завершення.

Обидва потребують скоупу content.read.

GET /api/external/orders

Список останніх замовлень акаунта, від найновіших. Без розбивки на завдання — для цього є ендпоінт деталей.

Параметри запиту

Параметр	Тип	Опис
`status`	string	Фільтрування за статусом замовлення.
`limit`	number	Скільки повернути. Обмежено до `[1, 50]`, за замовчуванням `20`.
`since`	string	Мітка часу ISO 8601; лише замовлення, створені пізніше.

Відповідь

{
  "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

Одне замовлення з повною розбивкою на завдання.

Параметри шляху

Параметр	Тип	Опис
`id`	string	UUID замовлення, повернений під час його створення.

Відповідь

{
  "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": "..."
    }
  ]
}

Поля завдання

Поле	Опис
`status`	`pending`, `in_progress`, `completed`, `failed`, `retry_pending`, `cancelled`, `expired`.
`attemptCount`	Скільки разів завдання запускалося. Значення понад 1 означає повторну спробу.
`outputUrl`	Згенерований ресурс. Заповнений лише для завдань `completed`, інакше `null`.
`errorCategory`	Чому завдання не вдалося — див. Категорії невдач завдань. `null`, якщо завдання не зазнало невдачі.
`errorHint`	Одне речення з поясненням категорії. Показуйте його людині, не парсіть.

Опитування статусу

Замовлення завершуються асинхронно. Опитуйте ендпоінт деталей, доки status не стане completed, failed або cancelled.

Дві речі, які варто знати перед написанням циклу:

Невдале завдання не завжди остаточне. TRANSIENT_INFRA, RATE_LIMIT і PROVIDER_CAPACITY повторюються автоматично, тож завдання може повідомити одну з цих категорій і все одно успішно завершитися на пізнішій спробі. Дивіться на status і attemptCount, а не на саму наявність errorCategory.

Часткове завершення — це нормально. Замовлення з кількома завданнями може завершитися так, що частина буде completed, а частина failed. Читайте jobsCompleted і jobsFailed, а не припускайте, що замовлення працює за принципом «все або нічого».

Пам'ятайте про ліміт 60 запитів на хвилину — див. Ліміти запитів. Опитування кожні кілька секунд на замовлення цілком достатньо; генерація триває значно довше.

Помилки

Код	Причина
`400`	`id` не є коректним UUID або параметр запиту неправильний.
`401`	Відсутній, недійсний або відкликаний ключ API.
`403`	Ключ не має скоупу `content.read`.
`404`	Замовлення не існує або належить іншому акаунту. Ці випадки навмисно нерозрізнювані.
`429`	Перевищено ліміт запитів.