Помилки

У цьому посібнику ми поговоримо про те, що відбувається, коли щось іде не так під час роботи з Meshy API.

Помилки запиту

Ці помилки повертаються негайно, коли ваш API-запит відхилено. Перевірте HTTP-код стану та поле message, щоб зрозуміти, що пішло не так.

{
  "message": "Invalid model file extension: .3dm"
}

Помилки завдання

Ці помилки виникають після створення завдання та під час його обробки. Перевірте об’єкт task_error у відповіді завдання, щоб дізнатися подробиці помилки.

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

Типи помилок

Поле type повідомляє широку категорію збою. Використовуйте його, щоб визначити стратегію повторної спроби.

Коди помилок

Коли присутнє поле code, воно ідентифікує конкретну проблему, щодо якої можна вжити дій. Нижче наведено повний довідник для кожного коду помилки.

image_too_complex

Ця помилка виникає, коли вхідне зображення або prompt описує об’єкт, який є надто геометрично складним для обробки моделлю 3D-генерації.

Поширені приклади:

• Щільні купи дрібних об’єктів (наприклад, ящик, повний фруктів, стос книг)
• Складні повторювані візерунки (наприклад, ґратчасті структури, риштування, дротяні сітки)
• Складні будівельні структури (наприклад, багатоповерхові будівлі з багатьма вікнами та балконами)
• Кілька окремих об’єктів на одному зображенні замість одного об’єкта

Приклади вхідних даних, які, ймовірно, є надто складними:

Вирішення:

1. Використовуйте один об’єкт на зображення. Модель найкраще працює з одним чітким об’єктом. Не включайте кілька окремих об’єктів в одне зображення або prompt.
2. Спростіть свій об’єкт. Зменште рівень деталізації. Наприклад, проста ваза замість вази, наповненої десятками квітів.
3. Уникайте prompt на рівні сцени. Цілі будівлі, міські квартали, інтер’єри, заповнені меблями, або ландшафти, ймовірно, перевищать можливості моделі. Натомість зосередьтеся на одному об’єкті.
4. Уникайте щільних повторюваних структур. Такі об’єкти, як риштування, дротяні сітки, ґратчасті візерунки або купи багатьох дрібних предметів, часто спричиняють цю помилку.

model_missing_uv

Ця помилка виникає, коли ви завантажуєте модель для текстурування з enable_original_uv, установленим на true, але модель не має UV-координат. UV-координати визначають, як 2D-текстура накладається на 3D-поверхню вашої моделі.

Рішення:

Правильне виправлення залежить від того, чому ви встановили enable_original_uv на true:

• Якщо вам потрібно зберегти оригінальну UV-розкладку вашої моделі (наприклад, користувацьке розміщення швів для точного мапінгу текстури): ваша модель повинна мати дійсні UV-координати. Перед завантаженням перевірте, що UV існують в UV-редакторі вашого 3D-програмного забезпечення. Зверніть увагу, що файли STL не можуть зберігати UV-дані, тому натомість використовуйте GLB, FBX або OBJ.
• Якщо вам не потрібен конкретний контроль UV (або ви не впевнені): пропустіть enable_original_uv або встановіть його на false. Система автоматично згенерує UV-розкладку для вашої моделі. Автоматично згенеровані UV оптимізовані для покриття, але ви не матимете контролю над тим, де розміщуються шви текстури.

model_insufficient_uv

Ця помилка виникає, коли модель має UV-координати, але покриття UV занадто мале для якісного текстурування. Це часто трапляється з моделями, експортованими з 3D-інструментів, які генерують тимчасові або стиснуті UV без належного розгортання.

Рішення:

• Якщо вам потрібно зберегти оригінальну UV-розкладку: повторно розгорніть UV моделі у своєму 3D-програмному забезпеченні. Переконайтеся, що UV-острови належно розподілені по UV-простору, а не стиснуті в невелику ділянку.
• Якщо вам не потрібен спеціальний контроль UV: пропустіть enable_original_uv або встановіть для нього значення false. Система автоматично згенерує нову UV-розкладку. Компроміс полягає в тому, що ви втратите оригінальне розміщення швів, але автоматично згенеровані UV матимуть належне покриття для текстурування.

invalid_input

Це резервний код помилки, коли вхідні дані не проходять перевірку, але не застосовується жоден конкретніший код. Поле message містить конкретну причину помилки.

Поширені причини:

• Порожні або пошкоджені файли моделей
• Непідтримувані варіації форматів файлів (наприклад, ASCII-файли FBX, GLB зі стисненням meshopt)
• У завантаженій моделі не знайдено дійсних 3D-об’єктів (наприклад, файл містить лише арматури, камери або джерела світла)
• Вміст, який не проходить фільтри безпеки

Рішення: Перевірте поле message, щоб дізнатися подробиці про те, що пішло не так. Переконайтеся, що ваші вхідні файли та параметри відповідають вимогам кінцевої точки.

moderation_blocked

Ця помилка виникає, коли ваш prompt або референсні зображення відхиляються фільтрами безпеки AI. Фільтр оцінює як текстовий prompt, так і будь-які референсні зображення разом.

Вирішення:

• Перефразуйте ваш текстовий prompt, щоб прибрати натякаючі або чутливі описи.
• Змініть референсні зображення, якщо вони зображують вміст, який може спрацювати фільтри безпеки.

timeout

Ця помилка означає, що час обробки вашого завдання перевищив дозволений ліміт. Це може статися через високе навантаження на систему або тому, що вхідні дані надто складні для обробки в межах ліміту часу.

Рішення:

1. Повторіть запит. Помилки timeout часто є тимчасовими, і повторна спроба може бути успішною.
2. Спростіть вхідні дані. Якщо повторні спроби й надалі не вдаються, ваші вхідні дані можуть бути надто складними. Спробуйте зменшити рівень деталізації у вашому зображенні або prompt. Див. image_too_complex, щоб отримати рекомендації щодо того, які типи вхідних даних складніше обробляти.

format_conversion_failed

Ця помилка виникає, коли згенеровану 3D-модель не вдалося перетворити у запитаний вами вихідний формат. Модель було успішно згенеровано, але етап перетворення завершився невдало.

Вирішення:

1. Повторіть запит.
2. Спробуйте інший вихідний формат. Якщо певний формат і далі завершується невдало, перейдіть на інший формат, який відповідає вашим потребам.

Найкращі практики

1. Реалізуйте логіку повторних спроб. Для помилок timeout і service_unavailable реалізуйте логіку повторних спроб з експоненційною затримкою.
2. Записуйте ідентифікатори завдань у журнал. Завжди записуйте ідентифікатор завдання в журнал для налагодження. Вказуйте його під час звернення до служби підтримки.
3. Перевіряйте вхідні дані. Переконайтеся, що ваші вхідні зображення та моделі відповідають вимогам до формату перед надсиланням.