Помилки

Дізнайтеся, чому запит або завдання завершилися невдачею, і що робити далі. Запит може завершитися невдачею одразу з HTTP-помилкою, а завдання — пізніше з task_error.

Request errors

Meshy повертає ці помилки одразу, коли відхиляє запит. Щоб дізнатися, що пішло не так, перевірте код стану HTTP і поле message.

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

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

Завдання, яке створив Meshy, все одно може завершитися невдало під час виконання. Його status стає FAILED, Meshy повертає його кредити, а 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."
  }
}

Error types

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

Коди помилок

Коли присутнє поле code, воно позначає одну з наведених нижче проблем.

image_too_complex

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

Наприклад:

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

Ці вхідні дані, ймовірно, надто складні:

Щоб виправити це, спробуйте один або кілька з наведених нижче варіантів:

• Використовуйте один об'єкт на зображення. Meshy найкраще працює з одним чітким об'єктом, тому не розміщуйте кілька окремих об'єктів на одному зображенні чи в одному prompt.
• Спростіть ваш об'єкт. Наприклад, використовуйте просту вазу замість вази, заповненої десятками квітів.
• Уникайте сцен. Цілі будівлі, міські квартали, умебльовані кімнати та пейзажі, ймовірно, будуть надто складними. Зосередьтеся на одному об'єкті.
• Уникайте щільних повторюваних структур. Риштування, дротяні сітки, решітки та купи дрібних предметів є поширеними причинами виникнення цієї проблеми.

model_missing_uv

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

Щоб виправити це, зробіть одне з наступного:

• Щоб зберегти власну UV-розкладку вашої моделі, наприклад для розміщення швів за власним задумом, додайте UV-координати до моделі у вашому 3D-редакторі. Перевірте їх у його UV-редакторі, а потім завантажте модель знову. Файли STL не можуть зберігати UV-координати, тому використовуйте GLB, FBX або OBJ.
• Якщо вам не потрібна власна розкладка, або ви не впевнені, пропустіть enable_original_uv або встановіть значення false. Тоді Meshy створить UV-розкладку для моделі. Нові UV-координати добре покривають модель, але ви не зможете контролювати розташування швів текстури.

model_insufficient_uv

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

Щоб виправити це, виконайте одну з таких дій:

• Щоб зберегти власну UV-розкладку, повторно розгорніть UV-координати моделі у своєму 3D-редакторі. Розподіліть острівці по всьому UV-простору, а не в маленькому куточку.
• Якщо власна розкладка вам не потрібна, не вказуйте enable_original_uv або встановіть значення false. Тоді Meshy створить нову UV-розкладку. Ви втратите розташування швів, але нові UV-координати покриватимуть достатньо простору для текстурування.

model_missing_texture

Вхідна модель завдання Multi-Color Print не має кольору, який Meshy може розділити на кольори друку. Meshy створює багатоколірний 3MF із кольорів моделі, тому звичайна біла сітка не дає матеріалу для роботи. Наприклад, попередній перегляд Text to 3D або Image to 3D, який ніколи не був текстурований, не має кольору. Так само не має його результат роботи Відновлення придатності до друку або завдання Auto Split, яке не зберегло текстуру.

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

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

Meshy відхиляє модель, яка не має ні базової текстури кольору, ні кольорів вершин, для обох стилів, замість того, щоб дозволити cartoon перетворити її на одноколірний друк.

Meshy відхиляє більшість таких запитів ще до створення завдання, повертаючи 400 з тим самим поясненням. Зазвичай ви отримуєте цей код лише тоді, коли Meshy не може перевірити вхідні дані заздалегідь. Наприклад, Meshy перевіряє завантажений .fbx лише після того, як завдання конвертує його.

Щоб виправити це, виберіть варіант, що підходить вашій моделі:

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

textured_split_refused

Завдання Auto Split з keep_texture: true не може зберегти текстуру вхідної моделі на частинах. Наприклад, модель не має UV-розгортки, або її текстура не має місця для нових граней, які створюють розрізи. Meshy повертає кредити.

Щоб виправити це, надішліть запит знову без keep_texture, або з keep_texture: false. Тоді частини повертаються з суцільним кольором кожна.

invalid_input

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

Наприклад:

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

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

moderation_blocked

Фільтри безпеки відхилили ваш prompt або референсні зображення. Фільтри перевіряють текст і зображення разом.

Щоб виправити це, виконайте одну або обидві дії:

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

moderation_unavailable

Тип: server_error. Модерація вмісту тимчасово була недоступна, тому Meshy завершив завдання з помилкою, замість того щоб пропустити перевірку. З вашим вмістом усе гаразд.

Щоб виправити це, створіть завдання ще раз.

timeout

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

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

Щоб це виправити, виконайте такі кроки:

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

queue_timeout

Тип: timeout. Завдання занадто довго очікувало в черзі, так і не розпочавшись, тому Meshy позначив його як невдале та повернув будь-які кредити, списані за нього. Ваші вхідні дані не спричинили цю помилку.

Щоб виправити це, створіть завдання знову.

format_conversion_failed

Meshy згенерував модель, але конвертація її у запитаний вами формат завершилася невдало.

Щоб виправити це, виконайте такі кроки:

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

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

• Повторюйте невдалі завдання. Для завдання, що завершилося помилкою з кодом timeout, service_unavailable або server_error, створюйте нове завдання з експоненційною затримкою.
• Не створюйте нове завдання, коли ваш власний запит перевищує час очікування. Перше завдання могло ще виконуватися, тому перевірте, чи воно існує, перш ніж створювати інше. Див. Скільки часу чекати.
• Записуйте ідентифікатори завдань у журнал. Вказуйте ID, коли звертаєтесь до служби підтримки.
• Перевіряйте вхідні дані перед надсиланням. Переконайтеся, що зображення та моделі відповідають вимогам до формату кінцевої точки.
• Викликайте API зі свого сервера. Код, що виконується в браузері, розкриває ваш API-ключ будь-кому, хто відкриє сторінку.