Ошибки

Узнайте, почему запрос или задача завершились неудачей, и что делать дальше. Запрос может завершиться неудачей сразу с ошибкой HTTP, а задача может завершиться неудачей позже с task_error.

Ошибки запросов

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."
  }
}

Типы ошибок

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

Чтобы это исправить, сделайте одно из следующего:

• Чтобы сохранить собственную UV-раскладку, заново разверните UV модели в своём 3D-редакторе. Распределите острова по всему UV-пространству, а не в небольшом его углу.
• Если вам не нужна собственная раскладка, не указывайте enable_original_uv или установите значение false. В этом случае Meshy создаст новую UV-раскладку. Вы потеряете расположение швов, но новые UV будут покрывать достаточно пространства для наложения текстуры.

model_missing_texture

Входная модель задачи Многоцветная печать не содержит цвета, который Meshy могла бы разделить на цвета печати. Meshy строит многоцветный 3MF на основе цветов модели, поэтому обычной белой сетке просто не с чем работать. Например, превью Текст в 3D или Изображение в 3D, которое никогда не текстурировалось, не имеет цвета. То же самое относится и к результату Восстановления пригодности к печати, а также к задаче Auto Split, в которой текстура не была сохранена.

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

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

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

Meshy отклоняет большинство таких запросов ещё до создания задачи, возвращая код 400 с тем же объяснением. Обычно этот код появляется только тогда, когда Meshy не может проверить входные данные заранее. Например, Meshy проверяет загруженный файл .fbx только после того, как задача преобразует его.

Чтобы это исправить, выберите вариант, подходящий для вашей модели:

• Сначала текстурируйте модель. Запустите Ретекстурирование на ней, либо сгенерируйте её с помощью задачи refine в Текст в 3D или задачи Изображение в 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 пометила её как неудачную (FAILED) и вернула все кредиты, списанные за неё. Ваши входные данные не стали причиной этой ошибки.

Чтобы исправить это, создайте задачу заново.

format_conversion_failed

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

Чтобы исправить это, выполните следующие шаги:

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

Best practices

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