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

> URL: https://help.meshy.ai/uk/articles/16102100-meshy-api-webhooks-vs-polling-when-results-are-ready
> Language: uk
> Last updated: 2026-09-09T11:02:40Z

Завдання генерації 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.

## Налаштування 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

Відповідь із `"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 щодо варіантів корпоративного плану.

## FAQ

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

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

### 2. Чи варто використовувати опитування чи webhooks?

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

### 3. Що має робити мій сервер, якщо він отримує той самий webhook двічі?

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

### 4. Мій webhook так і не надійшов — що робити?

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

### 5. Чи можу я повторити невдалу або незадовільну генерацію безпосередньо через API?

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

### 6. Скільки часу у мене є для завантаження результатів після статусу SUCCEEDED?

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

## Супутні статті

- [Чому я постійно стикаюся з помилками при отриманні моделей із результату генерації через API?](/uk/articles/9992036-why-do-i-consistently-encounter-errors-when-retrieving-the-models-from-generation-result-using-api)