Ошибки

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

moderation_unavailable

Эта ошибка возникает, когда модерация контента была временно недоступна, из-за чего задача завершилась неудачей вместо выполнения без проверки. С вашим контентом всё в порядке. Её type — server_error.

Решение: Создайте задачу заново.

timeout

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

Это отличается от timeout в вашем собственном коде. Если ваш клиент перестал ждать, задача всё ещё может выполняться; см. Жизненный цикл задачи.

Решение:

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

queue_timeout

Эта ошибка означает, что задача слишком долго ждала в очереди и не была запущена, поэтому она завершилась неудачей, а все списанные за неё кредиты были возвращены. Ваши входные данные не являются причиной этой ошибки. Её type — timeout.

Решение: Создайте задачу заново.

format_conversion_failed

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

Решение:

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

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

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