Ошибки

В этом руководстве мы расскажем о том, что происходит, когда что-то идёт не так во время работы с 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 будут иметь правильное покрытие для текстурирования.

model_missing_texture

Эта ошибка возникает, когда входная модель задачи многоцветной печати не содержит информации о цвете, которую конвертер мог бы разделить на цвета печати. Многоцветный 3MF строится на основе цветов модели, поэтому обычная белая сетка — например, предпросмотр Text to 3D или Image to 3D, для которого не создавалась текстура, либо результат восстановления / автоматического разделения — не даёт материала для работы.

То, что считается источником цвета, зависит от запрошенного style:

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

Модель, у которой нет ни базовой цветовой текстуры, ни цветов по вершинам, отклоняется для обоих стилей; в противном случае для cartoon она "успешно" превратилась бы в одноцветную печать.

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

Решение:

• Сначала создайте текстуру для модели. Запустите задачу Ретекстурирования для неё или создайте её с включённым текстурированием (задача refine для Text to 3D или задача 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, чтобы убрать намеки или чувствительные описания.
• Измените эталонные изображения, если они содержат контент, который может вызвать срабатывание фильтров безопасности.

timeout

Эта ошибка означает, что время обработки вашей задачи превысило допустимый предел. Это может произойти из-за высокой нагрузки на систему или потому, что ввод слишком сложен для обработки в пределах временного лимита.

Решение:

1. Повторите запрос. Таймауты часто являются временными, и повторная попытка может быть успешной.
2. Упростите ваш ввод. Если повторные попытки продолжают не удаваться, ваш ввод может быть слишком сложным. Попробуйте уменьшить уровень детализации в вашем изображении или prompt. См. image_too_complex для получения рекомендаций о том, какие типы вводов сложнее обрабатывать.

format_conversion_failed

Эта ошибка возникает, когда сгенерированная 3D-модель не может быть преобразована в запрашиваемый вами выходной формат. Модель была успешно сгенерирована, но этап преобразования завершился неудачей.

Решение:

1. Повторите запрос.
2. Попробуйте другой выходной формат. Если определенный формат продолжает давать сбой, переключитесь на другой формат, который соответствует вашим требованиям.

Лучшие практики

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