Жизненный цикл задачи
Узнайте, как задача проходит путь от запроса до результата, сколько времени это обычно занимает и как долго ваш код должен ожидать результата.
Как выполняется задача
Запрос на создание возвращает ID задачи, не дожидаясь её выполнения. Затем задача выполняется в фоновом режиме, и вы можете отслеживать её одним из трёх способов: опрашивать её GET-эндпоинт, открыть её потоковый эндпоинт или получить webhook.
PENDING. Воркер подхватывает её, и она переходит в статус IN_PROGRESS, в котором проводит большую часть времени. Завершается она статусом SUCCEEDED или FAILED, и финальный статус больше никогда не меняется.PENDINGIN_PROGRESSSUCCEEDEDFAILEDЗадача фиксирует каждый этап в полях created_at, started_at и finished_at.
В следующей таблице показано, что должен делать ваш код при каждом статусе.
| Статус | Что должен делать ваш код |
|---|---|
PENDING | Продолжать ждать. |
IN_PROGRESS | Отслеживать progress: процент выполненной работы, от 0 до 100. |
SUCCEEDED | Скачать результат. Meshy хранит файлы ограниченное время. См. Хранение ресурсов. |
FAILED | Прочитать task_error, затем исправить входные данные или создать новую задачу. См. Ошибки. |
CANCELED | Прекратить ожидание. Задача не даст результата. Этот статус используется только для задач Creative Lab. |
SUCCEEDED, FAILED и CANCELED — финальные статусы. После того как задача достигает одного из них, её статус больше никогда не меняется.
Со стороны вашего кода это выглядит так:
Запрос: POST/image-to-3d
Ответ: 202{ "result": "<task_id>" }задача создана
- Повторять каждые несколько секунд
Запрос: GET/image-to-3d/<task_id>
Ответ: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5
Запрос: GET/image-to-3d/<task_id>
Ответ: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }
GET позже с тем же ID задачи.Время обработки
В следующих таблицах показано медианное время на основе трафика продакшен-API за сентябрь 2026 года.
Время отсчитывается от создания задачи до финального статуса. Почти всё это время уходит на обработку, поскольку задача обычно остаётся в статусе PENDING всего несколько секунд. Когда очередь загружена, задачи могут дольше ждать начала выполнения, а задачи на тарифах с более высоким приоритетом обычно начинают выполняться быстрее.
Время менее 2 минут указано в секундах (с), а более длительное — в минутах (мин). «Не поддерживается» означает, что API не предлагает эту опцию для данной модели.
Это типичное время, а не гарантированное время завершения. В периоды высокой нагрузки некоторые задачи выполняются дольше, но всё равно успешно завершаются. Чтобы проверить статус Meshy, см. страницу статуса. Не используйте эти значения в качестве timeout в вашем коде. Значения timeout см. в разделе Сколько времени ждать.
Генерация 3D
| API | Конфигурация | meshy-7.1 (latest) | meshy-6 | meshy-6-lite | meshy-t2 |
|---|---|---|---|---|---|
| Текст в 3D (предпросмотр) | Только сетка | 75 с | 90 с | 45 с | 10 с |
| Изображение в 3D | Только сетка | 75 с | 90 с | 40 с | 4 с |
| Сетка с текстурами 2K | 2 мин | 3 мин | 75 с | 60 с | |
| Сетка с текстурами 4K | 2,5 мин | 3,5 мин | Не поддерживается | 80 с | |
| Сетка с текстурами 8K | 3,5 мин | 4 мин | Не поддерживается | 2,5 мин | |
| Мульти-изображение в 3D | Только сетка | 65 с | 2 мин | 30 с | Не поддерживается |
| Сетка с текстурами 2K | 2,5 мин | 3,5 мин | 85 с | Не поддерживается | |
| Сетка с текстурами 4K | 3 мин | 4 мин | Не поддерживается | Не поддерживается | |
| Сетка с текстурами 8K | 3,5 мин | 4,5 мин | Не поддерживается | Не поддерживается |
Для Изображение в 3D и Мульти-изображение в 3D «Только сетка» означает should_texture: false. Следующие опции и входные данные влияют на время:
- PBR-карты (
enable_pbr) добавляют от 30 до 60 секунд. - Ультра-геометрия (
geometry_resolution: "2k"или"4k") добавляет до 1 минуты. - При одинаковых настройках более сложные входные изображения требуют больше времени.
Текстурирование
| API | Разрешение текстуры | Типичное время |
|---|---|---|
| Текст в 3D (Refine) | 2K или 4K | 80 с |
| 8K | 3,5 мин | |
| Ретекстурирование | 2K | 55 с |
| 4K | 90 с | |
| 8K | 2,5 мин |
Генерация изображений
| API | nano-banana | nano-banana-2 | nano-banana-pro | Модели GPT Image |
|---|---|---|---|---|
| Текст в изображение | 20 с | 15 с | 25 с | от 20 до 35 с |
| Изображение в изображение | 40 с | 20 с | 30 с | от 20 до 40 с |
Rigging и Анимация
| API | Конфигурация | Типичное время |
|---|---|---|
| Auto-Rigging | Автоматический rigging | 40 с |
| Анимация | За запрос | 15 с |
| Текст в движение | mode prime | 15 с |
mode swift | 10 с |
Постобработка
| API | Типичное время |
|---|---|
| Ремешинг | 2 мин |
| UV-развёртка | 35 с |
| Конвертировать | 7 с |
| Изменить размер | 15 с |
3D-печать
| API | Конфигурация | Типичное время |
|---|---|---|
| Анализ пригодности к печати | Только проверка сетки | 1 с |
| Проверка сетки и тонких стенок | 10 с | |
| Multi-Color | За запрос | 30 с |
| Восстановление пригодности к печати | Только восстановление сетки | 10 с |
| Проверка тонких стенок, стенки сохранены | 20 с | |
| Проверка тонких стенок, стенки утолщены | 100 с | |
| Auto Split | Части сплошного цвета | 70 с |
Текстурированные части (keep_texture: true) | 170 с |
В v2 Восстановление пригодности к печати и Анализ пригодности к печати всегда выполняют проверку тонких стенок. В v1 эта проверка выполняется, если вы указываете тип принтера или размер печати.
Сколько времени ждать
Задача продолжает выполняться, даже если ваш код прекращает ожидание. Если у вашего запроса истекает timeout, соединение обрывается или поток закрывается, задача не завершается с ошибкой и не отменяется.
- Ждите не менее 60 минут, отсчитывая от
created_atзадачи, прежде чем прекратить ожидание. Если вы прекратите раньше, то можете пропустить задачу, которая завершится успешно позже. Чаще всего это происходит в периоды высокой нагрузки. - Сохраняйте ID задачи. Вы можете запросить задачу повторно в любой момент. Если через 60 минут она всё ещё не завершена, проверьте её снова позже. Если ситуация не меняется, обратитесь в поддержку.
- Только статус
FAILEDозначает, что задача завершилась с ошибкой. Meshy автоматически возвращает кредиты за неудачные задачи.
Используйте в коде следующие значения:
| Настройка | Рекомендуемое значение |
|---|---|
Timeout запроса на создание (POST) | 60 секунд |
Timeout запроса на создание (POST) с файлом model_url размером более 100 МБ | 120 секунд. Meshy скачивает файл, прежде чем ответить. |
Timeout запроса статуса (GET) | 30 секунд |
| Интервал опроса | Значение заголовка Retry-After, либо 5 секунд, если он отсутствует. Опросы учитываются в вашем ограничении частоты. |
Неудачный запрос статуса (timeout, 429 или 5xx) | Повторите попытку при следующем опросе. Это не означает, что задача завершилась с ошибкой. |
| Общее время ожидания на задачу | Не менее 60 минут от created_at. Не сбрасывайте этот отсчёт при переподключении потока. |
| Поток | Поток может закрыться до завершения задачи. Если он закрылся без финального статуса, переподключитесь или перейдите на опрос. |
Если у вас много задач одновременно, используйте webhooks вместо опроса каждой из них. Если финальное событие задачи не поступило спустя примерно удвоенное типичное время её выполнения, запросите задачу через её GET-эндпоинт.