# Meshy API: вебхуки или опрос \(polling\): когда результаты готовы > URL: https://help.meshy.ai/ru/articles/16102100-meshy-api-webhooks-vs-polling-when-results-are-ready > Language: ru > Last updated: 2026-09-09T10:54:57Z Задачи генерации Meshy API (Text to 3D, Image to 3D, Rigging и другие) выполняются асинхронно — вы отправляете задачу, а затем вам нужно узнать, когда она завершится, прежде чем получать результат. В этой статье описывается жизненный цикл задачи и два поддерживаемых способа узнать о её завершении: **опрос (polling)** и **вебхуки** — а также как избежать самой распространённой проблемы «ошибки при получении модели». ## Жизненный цикл задачи Каждая задача генерации проходит через небольшой набор состояний, которые возвращаются в поле `status` объекта задачи: - `PENDING` — задача поставлена в очередь, но обработка ещё не началась. - `IN_PROGRESS` — задача активно обрабатывается. Поле `progress` (0-100) увеличивается по мере выполнения работы. - `SUCCEEDED` — задача успешно завершена, `progress` равен 100. URL-адреса результатов (файлы моделей, текстуры, превью) теперь доступны в ответе. - `FAILED` — задачу не удалось завершить. Кредиты за неудачные задачи автоматически возвращаются. - `CANCELED` — задача была отменена до завершения. Самое важное правило при интеграции с API: **никогда не пытайтесь получить или использовать URL-адреса результатов, пока `status` задачи не равен `SUCCEEDED`**. Чтение результатов, пока задача находится в состоянии `PENDING` или `IN_PROGRESS`, — самая частая причина сообщений об «ошибках при получении модели». ## Пример опроса (polling) Опрос означает многократный вызов эндпоинта «get task» (получить задачу) для вашего ID задачи до тех пор, пока она не достигнет конечного состояния (`SUCCEEDED`, `FAILED` или `CANCELED`). Простой цикл опроса выглядит так: - Отправьте запрос на генерацию и сохраните возвращённый `id` задачи. - Периодически вызывайте соответствующий эндпоинт «retrieve task» (получить задачу) (например, эндпоинт Text to 3D или Image to 3D по ID задачи) — обычно интервал в несколько секунд. - Проверяйте поле `status` в каждом ответе. Продолжайте опрос, пока оно равно `PENDING` или `IN_PROGRESS`. - Прекратите опрос, как только `status` станет `SUCCEEDED` (прочитайте URL-адреса результатов), `FAILED` или `CANCELED`. - Добавьте в свой клиент разумный таймаут/ограничение на число попыток, чтобы зависшая задача не опрашивалась бесконечно. Опрос прост и хорошо подходит для скриптов, пакетных заданий и интеграций с небольшим объёмом. Для высоконагруженных интеграций или случаев, чувствительных к задержкам, вебхук обычно подходит лучше. ## Настройка вебхука Вместо того чтобы постоянно спрашивать «уже готово?», вы можете попросить Meshy уведомить ваш сервер в момент завершения задачи. Чтобы использовать вебхуки: - Настройте URL вебхука (callback), доступный для Meshy, — обычно он задаётся на уровне настроек аккаунта/API или передаётся как параметр в запросе на генерацию, в зависимости от эндпоинта. - Убедитесь, что ваш эндпоинт общедоступен по HTTPS и отвечает быстро (немедленно возвращайте статус 2xx, а затем обрабатывайте payload асинхронно). - Когда задача достигает конечного состояния, Meshy отправляет payload на ваш эндпоинт, содержащий `id` задачи и её итоговый `status`. - Получив его, получите полные сведения о задаче по `id` через API, а не полагайтесь только на тело вебхука, чтобы гарантировать наличие актуального и достоверного результата. Вебхуки сокращают количество ненужных вызовов API и обеспечивают почти мгновенное уведомление, но вам всё равно следует оставить периодический опрос в качестве резервного механизма для задач, в которых доставка вебхука может быть пропущена или задержана (например, из-за временной проблемы с сетью на вашей стороне). ## Идемпотентность Независимо от того, используете ли вы опрос или вебхуки, ваш код обработки результатов должен быть идемпотентным — безопасным для многократного выполнения для одной и той же задачи без побочных эффектов. Это важно, потому что: - Вебхук может быть доставлен более одного раза для одной и той же задачи (повторные попытки на стороне отправителя, дублирование в сети и т. д.). - Цикл опроса и обработчик вебхука могут одновременно попытаться обработать одну и ту же завершённую задачу, если оба запущены. Чтобы сохранить идемпотентность, стройте логику обработки на основе `id` задачи — например, проверяйте, не сохранили/не загрузили ли вы уже результаты для этого `id`, прежде чем делать это снова, и делайте «отметку как обработанную» одним атомарным шагом в вашей собственной базе данных. ### status = SUCCEEDED Ответ с `"status": "SUCCEEDED"` и `"progress": 100` — единственный сигнал, гарантирующий, что payload с результатом (URL-адреса модели, текстуры, миниатюры) полон и безопасен для использования. Конкретно в вашем коде: - Проверяйте `status === "SUCCEEDED"`, прежде чем читать что-либо из полей `result`/URL модели. - Не полагайтесь только на `progress` — всегда проверяйте и `status`, так как progress может на короткое время показывать высокие значения до того, как задача полностью финализирована. - Загружайте файлы результатов сразу после `SUCCEEDED` — сгенерированные ассеты хранятся на серверах Meshy только ограниченное время, после чего URL-адреса перестают работать. ## Распространённые ошибки Большинство сообщений «я не могу получить свою модель» связаны с одной из следующих причин: - **Слишком раннее обращение.** Вызов URL результата или чтение полей модели до того, как `status` станет `SUCCEEDED`. Это, безусловно, самая частая причина. - **Истёкшие ассеты.** Слишком долгое ожидание после `SUCCEEDED` перед загрузкой — URL-адреса результатов перестают работать после истечения срока хранения для данного типа задачи. - **Использование устаревшего или неверного ID задачи** — например, повторное использование ID из предыдущего несвязанного запроса. - **Восприятие `FAILED` как переходного состояния** и продолжение опроса уже провалившейся задачи вместо повторной отправки запроса. - **Проблемы с сетью/таймауты** между вашим сервером и Meshy, которые ошибочно принимаются за проблему генерации. ## Повторные попытки Если результат генерации не соответствует вашим ожиданиям или запрос полностью провалился, учитывайте следующее: - Meshy API в настоящее время не поддерживает повторный запуск существующей задачи — чтобы попробовать снова, отправьте новый запрос на генерацию, который будет расходовать кредиты как обычно. - При временных сбоях сети при вызовах API (таймауты, ответы 5xx) разумно использовать короткую экспоненциальную задержку перед повторной отправкой запроса. - При самом опросе повторяйте вызов «get task» при временных сетевых ошибках, но не считайте единичный неудачный опрос провалом генерации — доверяйте полю `status`, только получив успешный ответ. - Если вам нужна встроенная функциональность повторных попыток для генерации, обратитесь в отдел продаж Meshy по поводу вариантов корпоративного плана. ## FAQ ### 1. Почему я стабильно получаю ошибки при получении моделей из результата генерации через API? Это почти всегда происходит потому, что код пытается прочитать результат до завершения задачи. Всегда убеждайтесь, что `status` равен `SUCCEEDED` (а `progress` — 100), прежде чем получать URL-адреса модели. ### 2. Следует ли мне использовать опрос или вебхуки? Опрос проще настроить и он подходит для интеграций с небольшим объёмом или разовых скриптов. Вебхуки лучше подходят для производственных интеграций с множеством параллельных задач, так как они позволяют избежать лишних повторных запросов и немедленно уведомляют вас о завершении задачи. ### 3. Что должен делать мой сервер, если он получает один и тот же вебхук дважды? Обрабатывайте его идемпотентно — сверяйте `id` задачи с уже обработанными и пропускайте повторную обработку, если она уже была выполнена. ### 4. Мой вебхук так и не пришёл — что мне делать? Перейдите к опросу задачи напрямую по `id`. Также убедитесь, что ваш эндпоинт общедоступен по HTTPS и быстро возвращает ответ 2xx, так как медленные или недоступные эндпоинты могут вызывать проблемы с доставкой. ### 5. Могу ли я повторить неудавшуюся или неудовлетворительную генерацию напрямую через API? В настоящее время нет — вам нужно будет отправить новый запрос на генерацию, который расходует кредиты как обычно. Обратитесь в отдел продаж по поводу корпоративных вариантов, если вам нужна встроенная поддержка повторных попыток. ### 6. Сколько времени у меня есть на загрузку результатов после того, как статус стал SUCCEEDED? Файлы результатов хранятся на серверах Meshy только ограниченное время после завершения задачи, поэтому загружайте результаты в собственное хранилище, как только задача успешно завершится, а не ждите.