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, — самая частая причина сообщений об «ошибках при получении модели».

Опрос означает многократный вызов эндпоинта «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" и "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 по поводу вариантов корпоративного плана.

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

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

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

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

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

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

• Почему я стабильно сталкиваюсь с ошибками при получении моделей из результата генерации через API?