Meshy API: вебхуки vs опитування — коли результати готові

Завдання генерації Meshy API (Text to 3D, Image to 3D, Rigging тощо) виконуються асинхронно — ви надсилаєте завдання, а потім маєте дізнатися, коли його завершено, перш ніж отримувати результат. У цій статті пояснюється життєвий цикл завдання та два підтримувані способи дізнатися, коли завдання завершено: опитування та вебхуки, а також як уникнути найпоширенішої проблеми з «errors retrieving the model».

Кожне завдання генерації проходить через невеликий набір станів, які повертаються в полі status об'єкта завдання:

• PENDING — завдання поставлено в чергу, але обробка ще не почалася.

• IN_PROGRESS — завдання активно обробляється. Поле progress (0-100) зростає в міру виконання роботи.

• SUCCEEDED — завдання успішно завершено, а progress дорівнює 100. URL-адреси результатів (файли моделей, текстури, попередні перегляди) тепер доступні у відповіді.

• FAILED — завдання не вдалося завершити. Кредити за невдалі завдання повертаються автоматично.

• CANCELED — завдання було скасовано до завершення.

Найважливіше правило під час інтеграції з API: ніколи не намагайтеся отримати або використати URL-адреси результатів, доки status завдання не стане SUCCEEDED. Читання результатів, коли завдання ще перебуває в стані PENDING або IN_PROGRESS, — найпоширеніша причина повідомлень про "помилки під час отримання моделі".

Опитування означає повторний виклик ендпойнта "get task" для вашого ідентифікатора завдання, доки воно не досягне кінцевого стану (SUCCEEDED, FAILED або CANCELED). Простий цикл опитування виглядає так:

• Надішліть запит на генерацію та збережіть повернутий id завдання.

• Викликайте відповідний ендпойнт "retrieve task" (наприклад, ендпойнт завдання за ідентифікатором для Text to 3D або Image to 3D) через інтервал — зазвичай кілька секунд.

• Перевіряйте поле status у кожній відповіді. Продовжуйте опитування, поки воно має значення PENDING або IN_PROGRESS.

• Припиніть опитування, щойно status стане SUCCEEDED (прочитайте URL-адреси результатів), FAILED або CANCELED.

• Додайте у свій клієнт розумне обмеження часу очікування/максимальної кількості спроб, щоб зависле завдання не опитувалося нескінченно.

Опитування просте й добре працює для скриптів, пакетних завдань і низьконавантажених інтеграцій. Для високонавантажених інтеграцій або інтеграцій, чутливих до затримки, зазвичай краще підходить вебхук.

Замість того щоб постійно запитувати «чи вже готово?», ви можете попросити Meshy повідомити ваш сервер у момент завершення завдання. Щоб використовувати вебхуки:

• Налаштуйте URL вебхука (callback), доступний для Meshy — зазвичай він задається на рівні налаштувань облікового запису/API або передається як параметр у запиті на генерацію, залежно від ендпоінта.

• Переконайтеся, що ваш ендпоінт загальнодоступний через HTTPS і швидко відповідає (одразу повертайте статус 2xx, а потім обробляйте дані асинхронно).

• Коли завдання досягає термінального стану, Meshy надсилає на ваш ендпоінт дані, що містять id завдання та його фінальний status.

• Після отримання знайдіть повні відомості про завдання за id через API, а не покладайтеся лише на тіло вебхука, щоб переконатися, що ви маєте авторитетний актуальний результат.

Вебхуки зменшують кількість непотрібних викликів API і забезпечують майже миттєве сповіщення, але вам усе одно варто залишити періодичне опитування як резервний варіант для завдань, де доставку вебхука може бути пропущено або затримано (наприклад, через тимчасову мережеву проблему на вашому боці).

Незалежно від того, використовуєте ви опитування чи вебхуки, ваш код обробки результатів має бути ідемпотентним — безпечним для багаторазового запуску для одного й того самого завдання без побічних ефектів. Це важливо, тому що:

• Вебхук може надходити більше одного разу для одного й того самого завдання (повторні спроби на боці відправника, дублювання в мережі тощо).

• Цикл опитування та обробник вебхука можуть обидва намагатися обробити одне й те саме завершене завдання, якщо обидва запущені.

Щоб зберегти ідемпотентність, прив’яжіть логіку обробки до id завдання — наприклад, перевірте, чи ви вже зберегли/завантажили результати для цього id, перш ніж робити це знову, і зробіть «позначити як оброблене» єдиним атомарним кроком у вашій базі даних.

Відповідь із "status": "SUCCEEDED" та "progress": 100 — це єдиний сигнал, який гарантує, що дані результату (URL-адреси моделей, текстури, мініатюри) є повними й безпечними для використання. Конкретно, у вашому коді:

• Перевіряйте status === "SUCCEEDED", перш ніж читати будь-що з полів result/URL-адреси моделі.

• Не покладайтеся лише на progress — завжди перевіряйте також status, оскільки progress може короткочасно показувати високі значення, перш ніж завдання буде остаточно завершено.

• Завантажуйте файли результатів одразу після SUCCEEDED — згенеровані активи зберігаються на серверах Meshy лише протягом обмеженого часу, після чого URL-адреси більше не працюватимуть.

Більшість звітів «не можу отримати свою модель» зводяться до однієї з таких причин:

• Занадто раннє отримання. Виклик URL результату або читання полів моделі до того, як status став SUCCEEDED. Це, безумовно, найчастіша причина.

• Прострочені ресурси. Занадто довге очікування після SUCCEEDED перед завантаженням — URL результатів перестають працювати після завершення вікна зберігання для цього типу завдання.

• Використання застарілого або неправильного ідентифікатора завдання — наприклад, повторне використання ID з попереднього, не пов’язаного запиту.

• Ставлення до FAILED як до тимчасового стану й продовження опитування завдання, яке вже завершилося невдачею, замість повторного надсилання.

• Проблеми з мережею/тайм-аутом між вашим сервером і Meshy, які неправильно сприймаються як проблема генерації.

Якщо генерація не відповідає вашим очікуванням або запит повністю не вдається, зверніть увагу на таке:

• Meshy API наразі не підтримує повторну спробу наявного завдання на місці — щоб спробувати ще раз, надішліть новий запит на генерацію, який звичайним чином споживатиме кредити.

• Для тимчасових мережевих збоїв під час виклику API (тайм-аути, відповіді 5xx) доцільно застосувати коротку експоненційну затримку перед повторним надсиланням запиту.

• Щодо самого опитування, повторюйте виклик «get task» у разі тимчасових мережевих помилок, але не вважайте одну невдалу спробу опитування збоєм генерації — довіряйте полю status лише після отримання успішної відповіді.

• Якщо вам потрібна вбудована функція повторних спроб для генерацій, зверніться до відділу продажів Meshy щодо варіантів корпоративного плану.

Це майже завжди відбувається тому, що код намагається прочитати результат до завершення завдання. Завжди переконуйтеся, що status має значення SUCCEEDED (а progress — 100), перш ніж отримувати URL моделей.

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

Обробляйте це ідемпотентно — перевіряйте id завдання за тим, що ви вже обробили, і пропускайте повторну обробку, якщо його вже було оброблено.

Поверніться до опитування завдання за id безпосередньо. Також переконайтеся, що ваша кінцева точка загальнодоступна через HTTPS і швидко повертає відповідь 2xx, оскільки повільні або недоступні кінцеві точки можуть спричиняти проблеми з доставкою.

Наразі ні — вам потрібно надіслати новий запит на генерацію, який зазвичай споживає кредити. Зверніться до відділу продажів щодо корпоративних варіантів, якщо вам потрібна вбудована підтримка повторних спроб.

Файли результатів зберігаються на серверах Meshy лише обмежений час після завершення завдання, тому завантажуйте результати у власне сховище щойно завдання завершиться успішно, а не чекайте.