Помилки

У цьому посібнику ми розповімо про те, що відбувається, коли щось йде не так під час роботи з 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, але модель не має 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 матимуть належне покриття для текстурування.

model_missing_texture

Ця помилка виникає, коли вхідна модель завдання Multi-Color Print не містить інформації про колір, яку конвертер міг би розділити на кольори друку. Багатоколірний 3MF будується на основі кольорів моделі, тому проста біла сітка — наприклад, попередній перегляд Text to 3D або Image to 3D, який ніколи не був текстурований, або результат відновлення / автоматичного розділення — не має з чим працювати.

Що саме вважається джерелом кольору, залежить від запитаного вами style:

• realistic вибирає базову текстуру кольору через UV-координати моделі, тому вимагає єдину базову текстуру кольору з UV-координатами на кожній частині сітки.
• cartoon спрощує кольори по граням і приймає базову текстуру кольору на будь-якій частині або кольори по вершинах (COLOR_0).

Модель без базової текстури кольору та без кольорів вершин відхиляється для обох стилів; з cartoon вона інакше "успішно" оброблялася б як одноколірний друк.

Більшість запитів відхиляються ще до створення завдання (400 Bad Request з тим самим поясненням), тому зазвичай цей код ви побачите лише тоді, коли вхідні дані неможливо було перевірити заздалегідь — наприклад, завантаження .fbx перевіряється лише після того, як завдання його нормалізувало.

Вирішення:

• Спочатку затекстуруйте модель. Запустіть завдання Ретекстурування на ній, або згенеруйте її з увімкненою текстуризацією (завдання Text to 3D refine, або завдання Image to 3D з should_texture: true), і передайте це завдання як input_task_id.
• Моделі з кольорами вершин (сканування фотограмметрії, вручну розфарбовані сітки): запитайте style: "cartoon", яка читає COLOR_0.
• Частково текстуровані або багатотекстурні моделі за realistic: кожна частина сітки потребує UV-координат і однієї й тієї ж єдиної базової текстури кольору. Затекстуруйте решту частин або об'єднайте текстури в один атлас, або перейдіть на style: "cartoon".

invalid_input

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

Поширені причини включають:

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

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

moderation_blocked

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

Рішення:

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

timeout

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

Рішення:

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

format_conversion_failed

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

Розв'язання:

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

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

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