Життєвий цикл завдання
Дізнайтеся, як завдання проходить шлях від запиту до результату, скільки часу це зазвичай займає і скільки часу ваш код має очікувати на результат.
Як виконується завдання
Запит на створення повертає 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 (Preview) | Лише сітка | 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 с |
У 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.