Помилки

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

Вирішення:

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

moderation_unavailable

Ця помилка виникає, коли moderation вмісту тимчасово була недоступна, тому завдання завершилося невдачею замість виконання без перевірки. З вашим вмістом усе гаразд. Його type — server_error.

Вирішення: Створіть завдання знову.

timeout

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

Це відрізняється від timeout у вашому власному коді. Якщо ваш клієнт припинив очікування, завдання все ще виконується; див. Task Lifecycle.

Вирішення:

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

queue_timeout

Ця помилка означає, що завдання занадто довго очікувало в черзі і так і не почало виконуватися, тому воно завершилося невдало, а будь-які кредити, списані за нього, були повернуті. Ваші вхідні дані тут ні до чого. Її type — timeout.

Вирішення: Створіть завдання знову.

format_conversion_failed

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

Вирішення:

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

Best Practices

1. Реалізуйте логіку повторних спроб. Якщо завдання завершується помилкою timeout, service_unavailable або server_error, створіть його знову з експоненційною затримкою. Якщо ж тайм-аут стався у вашому власному запиті, не створюйте нове завдання: спершу перевірте існуюче (див. Життєвий цикл завдання).
2. Ведіть журнал ідентифікаторів завдань. Завжди фіксуйте ідентифікатор завдання для цілей налагодження. Вказуйте його під час звернення до служби підтримки.
3. Перевіряйте вхідні дані. Переконайтеся, що ваші вхідні зображення та моделі відповідають вимогам до формату перед надсиланням.
4. Викликайте API зі свого сервера. Код, що виконується в браузері, розкриє ваш API-ключ будь-кому, хто відкриє сторінку.