Ошибки

В этом руководстве мы расскажем о том, что происходит, когда что-то идет не так во время работы с 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 или референсные изображения отклоняются фильтрами безопасности ИИ. Фильтр оценивает как текстовый prompt, так и любые референсные изображения вместе.

Решение:

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

timeout

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

Решение:

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

format_conversion_failed

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

Решение:

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

Рекомендации

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