Життєвий цикл завдання
Дізнайтеся, як завдання проходить шлях від запиту до результату, скільки часу це зазвичай займає і скільки ваш код має чекати на результат.
Як виконується завдання
Запит на створення повертає ID завдання, не чекаючи на його виконання. Потім завдання виконується у фоновому режимі, і ви можете відстежувати його одним із трьох способів: опитувати його GET кінцеву точку, відкрити його потокову (stream) кінцеву точку або отримати 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 хвилин вказано в секундах (s), а довший — у хвилинах (min). Значення «не підтримується» означає, що API не пропонує цю опцію для цієї моделі.
Це типові значення часу, а не гарантований час завершення. У періоди високого навантаження деякі завдання виконуються довше, але все одно успішно завершуються. Щоб перевірити статус Meshy, див. сторінку статусу. Не використовуйте ці значення як timeout у вашому коді. Значення для timeout див. у розділі Скільки часу чекати.
3D-генерація
| API | Конфігурація | meshy-7.1 (latest) | meshy-6 | meshy-6-lite | meshy-t2 |
|---|---|---|---|---|---|
| Текст у 3D (Preview) | Лише сітка | 75 s | 90 s | 45 s | 10 s |
| Зображення у 3D | Лише сітка | 75 s | 90 s | 40 s | 4 s |
| Сітка з 2K текстурами | 2 min | 3 min | 75 s | 60 s | |
| Сітка з 4K текстурами | 2.5 min | 3.5 min | Не підтримується | 80 s | |
| Сітка з 8K текстурами | 3.5 min | 4 min | Не підтримується | 2.5 min | |
| Мульти-зображення у 3D | Лише сітка | 65 s | 2 min | 30 s | Не підтримується |
| Сітка з 2K текстурами | 2.5 min | 3.5 min | 85 s | Не підтримується | |
| Сітка з 4K текстурами | 3 min | 4 min | Не підтримується | Не підтримується | |
| Сітка з 8K текстурами | 3.5 min | 4.5 min | Не підтримується | Не підтримується |
Для Зображення у 3D та Мульти-зображення у 3D «Лише сітка» означає should_texture: false. Ці опції та вхідні дані впливають на час:
- PBR-карти (
enable_pbr) додають від 30 до 60 секунд. - Ultra-геометрія (
geometry_resolution: "2k"або"4k") додає до 1 хвилини. - За однакових налаштувань складніші вхідні зображення обробляються довше.
Текстурування
| API | Роздільна здатність текстури | Типовий час |
|---|---|---|
| Текст у 3D (Refine) | 2K або 4K | 80 s |
| 8K | 3.5 min | |
| Ретекстурування | 2K | 55 s |
| 4K | 90 s | |
| 8K | 2.5 min |
Генерація зображень
| API | nano-banana | nano-banana-2 | nano-banana-pro | Моделі GPT Image |
|---|---|---|---|---|
| Текст у зображення | 20 s | 15 s | 25 s | від 20 до 35 s |
| Зображення у зображення | 40 s | 20 s | 30 s | від 20 до 40 s |
Rigging та Анімація
| API | Конфігурація | Типовий час |
|---|---|---|
| Auto-Rigging | Автоматичний rigging | 40 s |
| Анімація | За запит | 15 s |
| Текст у рух | mode prime | 15 s |
mode swift | 10 s |
Пост-обробка
| API | Типовий час |
|---|---|
| Ремеш | 2 min |
| UV-розгортка | 35 s |
| Конвертувати | 7 s |
| Змінити розмір | 15 s |
3D-друк
| API | Конфігурація | Типовий час |
|---|---|---|
| Аналіз придатності до друку | Лише перевірки сітки | 1 s |
| Перевірки сітки та тонких стінок | 10 s | |
| Multi-Color | За запит | 30 s |
| Відновлення придатності до друку | Лише відновлення сітки | 10 s |
| Перевірка тонких стінок, стінки збережено | 20 s | |
| Перевірка тонких стінок, стінки потовщено | 100 s | |
| Auto Split | Частини одного кольору | 70 s |
Текстуровані частини (keep_texture: true) | 170 s |
У 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 кінцеву точку.