Webhooks чи опитування в Meshy API: коли результати готові

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Цикл опитування та обробник webhook можуть одночасно спробувати обробити те саме завершене завдання, якщо працюють обидва.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Чому я постійно стикаюся з помилками при отриманні моделей із результату генерації через API?