Опитування завдань і вебхуки 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. Додайте зворотний виклик із перевіркою
Об’єднайте наведений фрагмент із коректним тілом створення завдання, зберігши наявні поля конфігурації. Використовуйте публічну 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. Поєднайте опитування та зворотні виклики
Використовуйте спільний обробник завершення. Постійне обмеження унікальності за ID завдання й кінцевою дією запобігає подвійним сповіщенням чи запуску двох наступних робіт. Самої часової позначки недостатньо для подій різних завдань. Ігноруйте застарілі оновлення після кінцевого стану та забезпечте безпечний повтор після збою робочого процесу.
Якщо виклик не надійшов або стан незрозумілий, повторно запитайте збережений ID. Тайм-аут читання не є підставою навмання створювати ще одне платне завдання. Відрізняйте транспортну помилку від підтвердженого збою завдання та звіряйте стан перед повторним надсиланням.
4. Перевірте сценарії збоїв
До запуску повторіть виклик, передайте хибний секрет, затримайте доставлення та змоделюйте перезапуск робочого процесу. Кожне завершене завдання має дати один надійно збережений результат, а невдале — зберегти помилку. Далі скористайтеся посібником зі збереження результатів.
Джерела: схема уніфікованого API, приклад отримання завдання та документація вебхуків. Приклади пояснюють інтеграцію, а не вимірювання реальної генерації.
