Meshy API: вебхуки или polling — когда результаты готовы

Задачи генерации в 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 означает многократный вызов эндпоинта «получить задачу» для вашего ID задачи, пока она не достигнет терминального состояния (SUCCEEDED, FAILED или CANCELED). Простой цикл polling выглядит так:

• Отправьте запрос на генерацию и сохраните возвращённый id задачи.

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

• Проверяйте поле status в каждом ответе. Продолжайте polling, пока оно равно PENDING или IN_PROGRESS.

• Прекратите polling, как только status станет SUCCEEDED (прочитайте URL результатов), FAILED или CANCELED.

• Добавьте в клиент разумное ограничение по таймауту и максимальному числу попыток, чтобы зависшая задача не опрашивалась бесконечно.

Polling прост и хорошо подходит для скриптов, пакетных заданий и интеграций с небольшим объёмом запросов. Для высоконагруженных интеграций или интеграций, чувствительных к задержкам, обычно лучше подходит вебхук.

Вместо того чтобы постоянно спрашивать «уже готово?», вы можете попросить Meshy уведомить ваш сервер в момент завершения задачи. Чтобы использовать вебхуки:

• Настройте URL вебхука (callback), доступный для Meshy, — обычно он задаётся на уровне настроек аккаунта/API или передаётся параметром в запросе генерации, в зависимости от эндпоинта.

• Убедитесь, что ваш эндпоинт публично доступен по HTTPS и быстро отвечает (сразу возвращайте статус 2xx, а затем обрабатывайте payload асинхронно).

• Когда задача достигает терминального состояния, Meshy отправляет payload на ваш эндпоинт, содержащий id задачи и её финальный status.

• При получении запросите полные сведения о задаче по id через API, а не полагайтесь только на тело вебхука, чтобы гарантировать получение достоверного, актуального результата.

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

Независимо от того, используете вы polling или вебхуки, код обработки результатов должен быть идемпотентным — безопасным при повторном выполнении для одной и той же задачи, без побочных эффектов. Это важно, потому что:

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

• Цикл polling и обработчик вебхука могут оба попытаться обработать одну и ту же завершённую задачу, если работают одновременно.

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

Ответ с "status": "SUCCEEDED" и "progress": 100 — единственный сигнал, гарантирующий, что результат (URL моделей, текстуры, миниатюры) полностью сформирован и готов к использованию. В вашем коде это означает следующее:

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

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

• Скачивайте файлы результатов сразу после SUCCEEDED: сгенерированные ресурсы хранятся на серверах Meshy ограниченное время, после чего URL перестанут работать.

Большинство сообщений «не могу получить свою модель» сводятся к одной из следующих причин:

• Слишком ранний запрос. Вызов URL результата или чтение полей модели до того, как status стал SUCCEEDED. Это самая частая причина.

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

• Использование устаревшего или неверного task ID — например, повторное использование ID из предыдущего, не связанного с этим запроса.

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

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

Если генерация не оправдала ваших ожиданий или запрос завершился неудачей, учтите следующее:

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

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

• Что касается самого polling, повторяйте вызов "get task" при временных сетевых ошибках, но не считайте одну неудачную попытку polling сбоем генерации — доверяйте полю status только после успешного ответа.

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

Это почти всегда происходит потому, что код пытается прочитать результат до завершения задачи. Всегда проверяйте, что status равен SUCCEEDED (а progress — 100), прежде чем получать URL моделей.

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

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

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

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

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