Опрос задач и вебхуки PiAPI: надёжная обработка завершения

Принятие запроса на изображение или видео ещё требует обработки завершения. Для задач унифицированного API PiAPI сохраните ID, проверьте конечный статус и обработайте результат конкретной модели. Опрос удобен для первой интеграции; вебхуки позволяют серверу реагировать на окончание работы.

1. Сохраните ID задачи и ограничьте опрос

После создания запишите data.task_id рядом с ID своего задания. Запрашивайте ту же задачу серверным ключом API. Успешный ответ HTTP не доказывает завершение генерации: проверяйте data.status.

curl --fail-with-body --silent --show-error \
  "https://api.piapi.ai/api/v1/task/${PIAPI_TASK_ID}" \
  --header "x-api-key: ${PIAPI_API_KEY}"

При completed проверьте data.output по схеме модели; при failed сохраните data.error. Ограничьте число повторов, увеличивайте интервалы и добавляйте случайный разброс. Срок ожидания приложения — локальный выбор: его истечение не доказывает сбой или отмену удалённой задачи. Сохраните ID для последующей сверки.

2. Добавьте callback с проверкой подлинности

Объедините фрагмент ниже с корректным телом создания задачи, сохранив существующие поля конфигурации. Используйте публичный HTTPS-адрес и секрет из защищённого хранилища сервера. По документации PiAPI секрет передаётся в заголовке x-webhook-secret; проверьте его до приёма уведомления.

{
  "config": {
    "webhook_config": {
      "endpoint": "https://your-app.example/piapi/callback",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

JSON вебхука содержит timestamp и data. Убедитесь, что задача принадлежит приложению, надёжно сохраните событие или поставьте его в постоянную очередь и быстро ответьте кодом 2xx. Загрузки и долгую работу выполняйте вне HTTP-обработчика. Учитывайте дубли: документация описывает повторные отправки при отсутствии успешного ответа.

3. Объедините опрос и callback

Используйте общий обработчик завершения. Постоянное ограничение уникальности по ID задачи и завершающему действию предотвращает двойные уведомления и запуск двух следующих заданий. Одной временной метки недостаточно для различения событий разных задач. Игнорируйте устаревшие обновления после конечного состояния и обеспечьте безопасный повтор работы после сбоя воркера.

Если callback не пришёл или состояние неясно, снова запросите сохранённый ID. Тайм-аут чтения не повод вслепую создавать ещё одну платную задачу. Отличайте транспортную ошибку от подтверждённого сбоя задачи и сверяйте состояние перед повторной отправкой.

4. Проверьте сценарии сбоев

До запуска повторите callback, отправьте неверный секрет, задержите доставку и имитируйте перезапуск воркера. Каждая завершённая задача должна давать один устойчиво сохранённый результат; каждая неудачная — сохранять ошибку. Затем следуйте руководству по хранению результатов.

Источники: схема унифицированного API, пример получения задачи, документация вебхуков. Примеры показывают устройство интеграции, а не измерения реальной генерации.