API Изображение в 3D

API Изображение в 3D — это функция, позволяющая интегрировать возможности Meshy по преобразованию изображений в 3D в ваше собственное приложение. В этом разделе вы найдёте всю информацию, необходимую для начала работы с этим API.

POST/openapi/v1/image-to-3d

Create an Image to 3D Task

Этот эндпоинт позволяет создать новую задачу Изображение в 3D. См. Объект задачи Изображение в 3D, чтобы узнать, какие свойства включены в объект задачи Изображение в 3D.

Параметры

Обязателен только один из параметров input_task_id или image_url. Если указаны оба, приоритет отдаётся input_task_id.

Name
input_task_id
Type
string
Обязательный
Description
ID завершённой задачи генерации изображения, результат которой следует использовать в качестве входного изображения. Эта задача должна относиться к одному из следующих типов: Текст в изображение или Изображение в изображение. Кроме того, она должна быть выполнена через API, иметь статус SUCCEEDED и создавать ровно одно изображение.

Name
image_url
Type
string
Обязательный
Description
Предоставьте изображение, которое Meshy будет использовать при создании модели. В настоящее время поддерживаются форматы .jpg, .jpeg и .png.
Есть два способа предоставить изображение:
- Общедоступный URL: URL, доступный из публичного интернета.
- Data URI: закодированный в base64 Data URI изображения. Пример Data URI: data:image/jpeg;base64,<your base64-encoded image data>.

Name
model_type
Type
string
по умолчанию standard
Description
Укажите тип генерации 3D-сетки.
Доступные значения:
- standard: Обычная высокодетализированная генерация 3D-сетки.
- smart-topology: Выберите модель Smart Topology с помощью ai_model (meshy-t2).
- lowpoly (устаревшее, будет отключено 30 октября 2026 года): создаёт низкополигональную сетку, оптимизированную для получения более чистых полигонов. Вместо этого мы рекомендуем Meshy T2: smart-topology с meshy-t2.
Если выбран smart-topology, параметры topology, should_remesh и save_pre_remeshed_model игнорируются.
Поддержка lowpoly будет прекращена 30 октября 2026 года. После этой даты запросы с model_type: "lowpoly" будут возвращать ошибку. Мы рекомендуем перейти на Meshy T2 (model_type: "smart-topology" с ai_model: "meshy-t2"). Если выбран lowpoly, параметры ai_model, topology, target_polycount, should_remesh и save_pre_remeshed_model игнорируются.
Name
ai_model
Type
string
по умолчанию latest
Description
ID используемой модели. Доступные значения зависят от model_type.
Стандартная генерация (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (устаревшее): используйте вместо этого meshy-7.1.
Генерация Smart Topology (model_type: smart-topology):
- meshy-t2 (по умолчанию): модель Smart Topology — более чистая topology, естественно разделённые части, вывод в виде треугольников и число граней, которое можно задать с помощью target_polycount.
Name
geometry_resolution
Type
string
по умолчанию standard
Description
Проход генерации геометрии. 2k запускает проход Ultra с разрешением 2048³; 4k запускает его с разрешением 4096³ для максимальной детализации поверхности.
Доступные значения: standard, 2k, 4k
Требует meshy-7.1 или latest.
Name
ultra_mode
Type
boolean
⚠ устаревший
по умолчанию false
Description
Используйте вместо этого geometry_resolution. ultra_mode: true эквивалентен geometry_resolution: "2k".
Name
should_texture
Type
boolean
по умолчанию true
Description
Определяет, будут ли сгенерированы текстуры. Если установить значение false, этап текстурирования будет пропущен, и вы получите сетку без текстур.

Применяется только когда should_texture = true

Name
enable_pbr
Type
boolean
по умолчанию false
Description
Генерирует PBR-карты (metallic, roughness, normal) в дополнение к базовому цвету. Карта emission также включается, если ai_model равен meshy-6, за исключением texture_resolution: 8k. Модели meshy-6-lite, meshy-7.1 и latest не создают карту emission.
Name
texture_resolution
Type
string
по умолчанию 2k
Description
Разрешение текстуры базового цвета. Одно из значений: 2k (2048×2048), 4k (4096×4096) или 8k (8192×8192). Более высокое разрешение позволяет захватить больше деталей поверхности.
Значения 4k и 8k недоступны для ai_model meshy-6-lite. При 8k карта emission не создаётся.
Name
hd_texture
Type
boolean
⚠ устаревший
по умолчанию false
Description
Используйте вместо этого texture_resolution — эквивалентно texture_resolution: "4k". Если указаны оба параметра, приоритет отдаётся texture_resolution.
Name
texture_prompt
Type
string
Description
Укажите текстовый prompt для управления процессом текстурирования. Максимум 800 символов.
Name
texture_image_url
Type
string
Description
Предоставьте 2D-изображение для управления процессом текстурирования. В настоящее время поддерживаются форматы .jpg, .jpeg и .png.
Есть два способа предоставить изображение:
- Общедоступный URL: URL, доступный из публичного интернета
- Data URI: закодированный в base64 Data URI изображения. Пример Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Текстурирование по изображению может работать не оптимально при значительных различиях в геометрии между исходным asset и загруженным изображением. Для управления процессом текстурирования можно использовать только один из параметров: texture_image_url или texture_prompt. Если указаны оба параметра, по умолчанию для текстурирования модели будет использоваться texture_prompt. Текстурирование как по тексту, так и по изображению стоит 10 кредитов за задачу.

Name
should_remesh
Type
boolean
по умолчанию false (Meshy 6 and Meshy 7 models), true (others)
Description
Определяет, включён ли этап ремешинга. Для получения модели наивысшего качества рекомендуется установить should_remesh в значение false.

Применяется только когда should_remesh = true

Name
topology
Type
string
по умолчанию triangle
Description
Укажите topology создаваемой модели.
Доступные значения:
- quad: создать сетку с преобладанием четырёхугольников.
- triangle: создать прореженную треугольную сетку.
Name
decimation_mode
Type
integer
Description
Включает адаптивное прореживание, задавая уровень числа полигонов. Если установлено, target_polycount игнорируется.
Доступные значения:
- 1: адаптивное — сверхвысокое число полигонов.
- 2: адаптивное — высокое число полигонов.
- 3: адаптивное — среднее число полигонов.
- 4: адаптивное — низкое число полигонов.
Name
save_pre_remeshed_model
Type
boolean
по умолчанию false
Description
Если установлено значение true, Meshy также сохраняет дополнительный файл GLB до завершения этапа ремешинга.

Name
target_polycount
Type
integer
Description
Целевое число полигонов (граней) в итоговой модели. Фактическое число может отличаться от целевого в зависимости от геометрии.
Параметр target_polycount вступает в силу в двух независимых случаях:
- Ремешинг — при should_remesh: true для модели standard. Сетка подвергается ремешингу (прореживанию) примерно до указанного числа. Диапазон от 100 до 300 000, по умолчанию 30 000. Если задан decimation_mode, он имеет приоритет, а target_polycount игнорируется.
- Smart Topology — при model_type: smart-topology и ai_model: meshy-t2. Модель создаётся сразу с указанным числом граней; этап ремешинга не выполняется, и should_remesh не требуется. Диапазон от 100 до 15 000, по умолчанию 4 000.

Name
symmetry_mode
Type
string
⚠ устаревший
по умолчанию auto
Description
Устаревшее. Этот параметр больше не влияет на результат.
Поле symmetry_mode управляет поведением симметрии в процессе генерации модели.
Допустимые значения:
- off: отключает симметрию.
- auto: автоматически определяет и применяет симметрию на основе входной геометрии.
- on: принудительно применяет симметрию при генерации.
Name
pose_mode
Type
string
по умолчанию ""
Description
Укажите режим позы для создаваемой модели.
Доступные значения:
- a-pose: сгенерировать модель в позе A.
- t-pose: сгенерировать модель в позе T.
- "" (пустая строка): без конкретной позы.
Name
is_a_t_pose
Type
boolean
⚠ устаревший
по умолчанию false
Description
Используйте вместо этого pose_mode. Определяет, создавать ли модель в позе A/T.
Name
image_enhancement
Type
boolean
по умолчанию true
Description
Оптимизирует входное изображение для получения лучших результатов. Установите значение false, чтобы сохранить точный внешний вид входного изображения без какой-либо стилевой обработки.
Поддерживается только если ai_model равен meshy-6, meshy-7.1 или latest.
Name
remove_lighting
Type
boolean
по умолчанию true
Description
Удаляет блики и тени с текстуры базового цвета, что даёт более чистый результат, лучше подходящий для пользовательских схем освещения.
Поддерживается только если ai_model равен meshy-6.
Name
moderation
Type
boolean
по умолчанию false
Description
Если установлено значение true, входной контент будет автоматически проверен на потенциально опасное содержимое. Если такое содержимое обнаружено, задача не будет переведена на этап генерации.
Проверке подвергается контент из параметров image_url, texture_image_url и texture_prompt.
Name
target_formats
Type
string[]
Description
Указывает, какие форматы 3D-файлов включить в результат. Будут сгенерированы и возвращены только запрошенные форматы, что может сократить время выполнения задачи. Если параметр не указан, включаются все поддерживаемые форматы.
Доступные значения: glb, obj, fbx, stl, usdz, 3mf
Если параметр не указан, генерируются все форматы, кроме 3mf. 3mf включается только при явном указании.
Name
auto_size
Type
boolean
по умолчанию false
Description
Если установлено значение true, сервис использует AI-зрение для автоматической оценки реальной высоты объекта и соответствующего изменения размера модели. Начало координат по умолчанию будет равно bottom, если origin_at не задано явно.
Name
alpha_thumbnail
Type
boolean
по умолчанию false
Description
Если установлено значение true, задача дополнительно отрисовывает версию превью с прозрачным фоном (RGBA) и возвращает её как alpha_thumbnail_url в ответе GET. Существующее поле thumbnail_url остаётся без изменений.
Name
multi_view_thumbnails
Type
boolean
по умолчанию false
Description
Если установлено значение true, задача дополнительно отрисовывает четыре миниатюры по основным направлениям (спереди, справа, сзади, слева) и возвращает их в thumbnail_urls в ответе GET. Существующее поле thumbnail_url остаётся без изменений и по-прежнему указывает на вид спереди, поэтому существующие клиенты не затрагиваются.
Увеличивает время выполнения задачи примерно на 3 секунды.

Применяется только когда auto_size = true

Name
origin_at
Type
string
по умолчанию bottom
Description
Положение начала координат, когда включён auto_size.
Доступные значения: bottom, center.

Возвращаемое значение

Свойство result ответа содержит id задачи только что созданной задачи Изображение в 3D.

Виды сбоев

Name
400 - Bad Request
Description
Запрос недопустим. Типичные причины:
- Отсутствует параметр: необходимо указать либо image_url, либо input_task_id.
- Недопустимая входная задача: input_task_id должен ссылаться на задачу Текст в изображение или Изображение в изображение со статусом SUCCEEDED, создающую ровно одно изображение.
- Недопустимый формат изображения: указанный image_url имеет неподдерживаемый формат (.jpg, .jpeg, .png).
- URL недоступен: не удалось загрузить image_url (404 или timeout).
- Недопустимый Data URI: строка base64 некорректна.
- Недопустимая комбинация параметров: enable_pbr поддерживается только если should_texture равен true.
- Неподдерживаемая модель для low poly: ai_model: "meshy-6-lite" не поддерживает model_type: "lowpoly".
- Неподдерживаемая модель для Ultra: geometry_resolution требует meshy-7.1 или latest.
Name
401 - Unauthorized
Description
Ошибка аутентификации. Проверьте ваш API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
429 - Too Many Requests
Description
Превышено ограничение частоты запросов.

Request

POST

/openapi/v1/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/image-to-3d/:id

Получить задачу изображения в 3D

Этот эндпоинт позволяет получить задачу изображения в 3D по действительному id задачи. Обратитесь к разделу Объект задачи Изображение в 3D, чтобы узнать, какие свойства включены в объект задачи Изображение в 3D.

Параметры

Name
id
Type
path
Description
Уникальный идентификатор задачи Изображение в 3D, которую требуется получить.

Возвращаемое значение

Ответ содержит объект задачи Изображение в 3D. Подробности см. в разделе Объект задачи Изображение в 3D.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

DELETE/openapi/v1/image-to-3d/:id

Удаление задачи Изображение в 3D

Этот эндпоинт безвозвратно удаляет задачу Изображение в 3D, включая все связанные модели и данные. Это действие необратимо.

Параметры пути

Name
id
Type
path
Description
ID задачи Изображение в 3D, которую нужно удалить.

Статус задачи

Задача, которая всё ещё находится в статусе PENDING, удаляется, а кредиты, списанные при её создании, возвращаются.

Задача, которая уже находится в статусе IN_PROGRESS, не может быть удалена: запрос отклоняется с ошибкой 409 Conflict, а задача продолжает выполняться. Кредиты за задачу, выполнение которой уже началось на воркере, не подлежат возврату, поэтому удаление её в процессе выполнения будет стоить вам и кредитов, и результата. Дождитесь, пока она перейдёт в статус SUCCEEDED, FAILED или CANCELED, а затем удалите её.

Задача в конечном статусе (SUCCEEDED, FAILED или CANCELED) удаляется без возврата средств.

Возвращает

Возвращает 200 OK при успешном выполнении или 409 Conflict, если задача находится в статусе IN_PROGRESS.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/image-to-3d

Получение списка задач Изображение в 3D

Этот эндпоинт позволяет получить список задач Изображение в 3D.

Параметры

Необязательные атрибуты

Name
page_num
Type
integer
Description
Номер страницы для пагинации. Начинается со значения 1, которое также является значением по умолчанию.
Name
page_size
Type
integer
Description
Лимит размера страницы. По умолчанию 10 элементов. Максимально допустимое значение — 100 элементов.
Name
sort_by
Type
string
Description
Поле для сортировки. Доступные значения:
- +created_at: Сортировка по времени создания в порядке возрастания.
- -created_at: Сортировка по времени создания в порядке убывания.

Возвращаемые значения

Возвращает список объектов задачи Изображение в 3D с пагинацией.

Request

GET

/openapi/v1/image-to-3d

curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

Стриминг задачи Image to 3D

Этот эндпоинт передаёт обновления в реальном времени для задачи Изображение в 3D с использованием Server-Sent Events (SSE).

Параметры

Name
id
Type
path
Description
Уникальный идентификатор задачи Изображение в 3D для стриминга.

Возвращает

Возвращает поток объектов задачи Изображение в 3D в виде Server-Sent Events.

Для задач со статусом PENDING или IN_PROGRESS поток ответа будет содержать только необходимые поля progress и status.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
  "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
  "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
  "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

Объект задачи Изображение в 3D

Объект задачи Изображение в 3D — это единица работы, которую Meshy отслеживает для генерации 3D-модели из входного изображения. Объект имеет следующие свойства:

Свойства

Name
id
Type
string
Description
Уникальный идентификатор задачи. Хотя в качестве деталей реализации мы используем k-sortable UUID для идентификаторов задач, вам не следует делать никаких предположений о формате id.
Name
type
Type
string
Description
Тип задачи Изображение в 3D. Значение — image-to-3d.
Name
model_urls
Type
object
Description
Ссылка для скачивания текстурированного файла 3D-модели, сгенерированного Meshy. Свойство для формата будет отсутствовать, если этот формат не был сгенерирован, вместо возврата пустой строки.
- Name
  glb
  Type
  string
  Description
  Ссылка для скачивания файла GLB.
- Name
  fbx
  Type
  string
  Description
  Ссылка для скачивания файла FBX.
- Name
  obj
  Type
  string
  Description
  Ссылка для скачивания файла OBJ.
- Name
  usdz
  Type
  string
  Description
  Ссылка для скачивания файла USDZ.
- Name
  mtl
  Type
  string
  Description
  Ссылка для скачивания файла MTL, возвращается вместе с экспортом OBJ при наличии текстур.
- Name
  stl
  Type
  string
  Description
  Ссылка для скачивания файла STL.
- Name
  3mf
  Type
  string
  Description
  Ссылка для скачивания файла 3MF. Присутствует только если 3mf был запрошен через target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Ссылка для скачивания исходного результата GLB до ремешинга.
  Доступно только если задача была создана одновременно с should_remesh: true и save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
Ссылка для скачивания миниатюры файла модели. Эквивалентно thumbnail_urls.front, когда оно присутствует, сохранено для обратной совместимости.
Name
alpha_thumbnail_url
Type
string
Description
Ссылка для скачивания версии thumbnail_url с прозрачным фоном (RGBA). Присутствует только если задача была создана с alpha_thumbnail: true и прозрачное превью было успешно отрендерено; в противном случае это поле отсутствует.
Name
thumbnail_urls
Type
object
Description
Ссылки для скачивания четырёх миниатюр сгенерированной 3D-модели с видами по основным направлениям. Каждое значение — подписанная ссылка на PNG размером 512×512, отрендеренный с теми же материалами и освещением, что и thumbnail_url. Полезно для предварительного просмотра модели с разных углов в пакетных конвейерах без скачивания GLB.
Присутствует только если задача была создана с multi_view_thumbnails: true и достигла статуса SUCCEEDED. Более старые задачи и задачи, созданные без этой опции, не будут включать это поле.
- Name
  front
  Type
  string
  Description
  Вид спереди, поворот на 0° вокруг вертикальной оси (совпадает с thumbnail_url).
- Name
  right
  Type
  string
  Description
  Вид справа, поворот на 90°.
- Name
  back
  Type
  string
  Description
  Вид сзади, поворот на 180°.
- Name
  left
  Type
  string
  Description
  Вид слева, поворот на 270°.
Name
texture_prompt
Type
string
Description
Текстовый prompt, который использовался для управления процессом текстурирования.
Name
texture_image_url
Type
string
Description
Ссылка для скачивания изображения текстуры, которое использовалось для управления процессом текстурирования.
Name
ultra_mode
Type
boolean
⚠ устаревший
Description
Устаревшее; используйте вместо этого geometry_resolution.
Name
geometry_resolution
Type
string
Description
Уровень Ultra, на котором выполнялась задача (2k или 4k); отсутствует для standard.
Name
progress
Type
integer
Description
Прогресс выполнения задачи. Если задача ещё не начата, это свойство будет равно 0. После успешного завершения задачи оно станет равным 100.
Name
started_at
Type
timestamp
Description
Временная метка начала выполнения задачи, в миллисекундах. Если задача ещё не начата, это свойство будет равно 0.
Временная метка представляет собой количество миллисекунд, прошедших с 1 января 1970 года UTC, в соответствии со стандартом RFC 3339. Например, пятница, 1 сентября 2023 года, 12:00:00 по GMT представляется как 1693569600000. Это применимо к всем временным меткам в Meshy API.
Name
created_at
Type
timestamp
Description
Временная метка создания задачи, в миллисекундах.
Name
expires_at
Type
timestamp
Description
Временная метка истечения срока действия результата задачи, в миллисекундах.
Name
finished_at
Type
timestamp
Description
Временная метка завершения задачи, в миллисекундах. Если задача ещё не завершена, это свойство будет равно 0.
Name
status
Type
string
Description
Статус задачи. Возможные значения: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Массив объектов ссылок на текстуры, сгенерированных в рамках задачи. Обычно он содержит только один объект ссылки на текстуру. Каждая ссылка на текстуру имеет следующие свойства:
- Name
  base_color
  Type
  string
  Description
  Ссылка для скачивания изображения карты базового цвета.
- Name
  metallic
  Type
  string
  Description
  Ссылка для скачивания изображения карты металличности.
  Если задача создана с enable_pbr: false, это свойство будет отсутствовать.
- Name
  normal
  Type
  string
  Description
  Ссылка для скачивания изображения карты нормалей.
  Если задача создана с enable_pbr: false, это свойство будет отсутствовать.
- Name
  roughness
  Type
  string
  Description
  Ссылка для скачивания изображения карты шероховатости.
  Если задача создана с enable_pbr: false, это свойство будет отсутствовать.
- Name
  emission
  Type
  string
  Description
  Ссылка для скачивания изображения карты излучения (emission).
  Если задача создана с enable_pbr: false, либо ai_model имеет значение meshy-6-lite, meshy-7.1 или latest, это свойство будет отсутствовать.
Name
preceding_tasks
Type
integer
Description
Количество задач, предшествующих текущей.
Значение этого поля имеет смысл только если статус задачи — PENDING.
Name
task_error
Type
object
Description
Детали ошибки для неудачных задач. См. раздел Ошибки для полного описания объекта task_error.
Name
consumed_credits
Type
integer
Description
Количество кредитов, потраченных на эту задачу. Присутствует, когда статус задачи — PENDING, IN_PROGRESS или SUCCEEDED. Возвращает 0 для задач со статусом FAILED (кредиты возвращаются при неудаче).

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}