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

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

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

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

Этот эндпоинт позволяет создать новую задачу Изображение в 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 (устаревшее): генерирует низкополигональную сетку, оптимизированную для более чистых полигонов. Рекомендуем использовать вместо этого smart-topology.
При выборе smart-topology параметры topology, should_remesh и save_pre_remeshed_model игнорируются.
При выборе 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-5, meshy-6, meshy-7, latest (Meshy 7)
Генерация Smart Topology (model_type: smart-topology):
- meshy-t2 (по умолчанию): модель Smart Topology — более чистая topology, изначально разделённые части, вывод в треугольниках и число граней, которое можно задать через target_polycount.
Name
ultra_mode
Type
boolean
по умолчанию false
Description
Включает генерацию Ultra для более точной геометрии с более детальной проработкой поверхности.
Поддерживается только при ai_model равном meshy-7 (или latest).
Name
should_texture
Type
boolean
по умолчанию true
Description
Определяет, будут ли сгенерированы текстуры. Установка значения false пропускает этап текстурирования, предоставляя сетку без текстур.

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

Name
enable_pbr
Type
boolean
по умолчанию false
Description
Генерировать PBR-карты (металличность, шероховатость, нормали) в дополнение к базовому цвету. Карта эмиссии также включается, если ai_model равен meshy-6, за исключением texture_resolution: 8k. meshy-7 и latest не создают карту эмиссии.
Name
texture_resolution
Type
string
по умолчанию 2k
Description
Разрешение текстуры базового цвета. Одно из значений: 2k (2048×2048), 4k (4096×4096) или 8k (8192×8192). Более высокое разрешение позволяет захватить больше деталей поверхности.
4k и 8k недоступны при ai_model: meshy-5. При 8k карта эмиссии не создаётся.
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>
Текстурирование по изображению может работать неоптимально при значительных различиях в геометрии между исходным ассетом и загруженным изображением. Для управления процессом текстурирования можно использовать только один из параметров: texture_image_url или texture_prompt. Если указаны оба параметра, то по умолчанию для текстурирования модели будет использоваться texture_prompt. Текстурирование как по тексту, так и по изображению стоит 10 кредитов за задачу.

Name
should_remesh
Type
boolean
по умолчанию false (meshy-6, meshy-7), 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 или 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, сервис использует компьютерное зрение на основе ИИ для автоматической оценки реального размера объекта по высоте и соответствующего изменения размера модели. Начало координат по умолчанию будет 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.
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 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>",
    "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 для подробностей.

Запрос

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

Ответ

{
  "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 для удаления.

Возвращает

Возвращает 200 OK в случае успеха.

Запрос

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

Ответ

// Returns 200 Ok on success.

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

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

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

Параметры

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

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

Возвращает

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

Запрос

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

Ответ

[
  {
    "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

Потоковая передача задачи "Изображение в 3D"

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

Параметры

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

Возвращает

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

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

Запрос

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

Поток ответа

// 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-сортируемый UUID для идентификаторов задач как деталь реализации, вы не должны делать никаких предположений о формате id.
Name
type
Type
string
Description
Тип задачи "Изображение в 3D". Значение — image-to-3d.
Name
model_urls
Type
object
Description
Загружаемый URL-адрес текстурированного 3D файла модели, сгенерированного Meshy. Свойство для формата будет опущено, если формат не сгенерирован, вместо возврата пустой строки.
- Name
  glb
  Type
  string
  Description
  Загружаемый URL-адрес файла GLB.
- Name
  fbx
  Type
  string
  Description
  Загружаемый URL-адрес файла FBX.
- Name
  obj
  Type
  string
  Description
  Загружаемый URL-адрес файла OBJ.
- Name
  usdz
  Type
  string
  Description
  Загружаемый URL-адрес файла USDZ.
- Name
  mtl
  Type
  string
  Description
  Загружаемый URL-адрес файла MTL, возвращается вместе с экспортами OBJ, когда присутствуют текстуры.
- Name
  stl
  Type
  string
  Description
  Загружаемый URL-адрес файла STL.
- Name
  3mf
  Type
  string
  Description
  Загружаемый URL-адрес файла 3MF. Присутствует только, когда 3mf был запрошен через target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Загружаемый URL-адрес оригинального вывода GLB до ремешинга.
  Доступно только, когда задача была создана с should_remesh: true и save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
Загружаемый URL-адрес изображения миниатюры файла модели. Эквивалентен thumbnail_urls.front, когда присутствует, сохранен для обратной совместимости.
Name
alpha_thumbnail_url
Type
string
Description
Загружаемый URL-адрес версии thumbnail_url с прозрачным фоном (RGBA). Присутствует только, когда задача была создана с alpha_thumbnail: true и прозрачный предварительный просмотр был успешно отрендерен; в противном случае это поле опущено.
Name
thumbnail_urls
Type
object
Description
Загружаемые URL-адреса для четырех миниатюр с кардинальными видами сгенерированной 3D модели. Каждое значение — это подписанный URL-адрес на 512×512 PNG, отрендеренный с теми же материалами и освещением, что и 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
Загружаемый URL-адрес изображения текстуры, использованного для управления процессом текстурирования.
Name
ultra_mode
Type
boolean
Description
Отражает значение ultra_mode, с которым была создана задача. Присутствует только для задач meshy-7 (или latest), которые явно установили ultra_mode; в противном случае опущено.
Name
progress
Type
integer
Description
Прогресс задачи. Если задача еще не начата, это свойство будет 0. Как только задача будет выполнена, это станет 100.
Name
started_at
Type
timestamp
Description
Временная метка начала задачи в миллисекундах. Если задача еще не начата, это свойство будет 0.
Временная метка представляет количество миллисекунд, прошедших с 1 января 1970 года по UTC, в соответствии с RFC 3339 стандартом. Например, пятница, 1 сентября 2023 года, 12:00:00 по Гринвичу представляется как 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
Массив объектов URL-адресов текстур, сгенерированных из задачи. Обычно это содержит только один объект URL-адреса текстуры. Каждый URL-адрес текстуры имеет следующие свойства:
- Name
  base_color
  Type
  string
  Description
  Загружаемый URL-адрес изображения карты базового цвета.
- Name
  metallic
  Type
  string
  Description
  Загружаемый URL-адрес изображения металлической карты.
  Если задача создана с enable_pbr: false, это свойство будет опущено.
- Name
  normal
  Type
  string
  Description
  Загружаемый URL-адрес изображения карты нормалей.
  Если задача создана с enable_pbr: false, это свойство будет опущено.
- Name
  roughness
  Type
  string
  Description
  Загружаемый URL-адрес изображения карты шероховатости.
  Если задача создана с enable_pbr: false, это свойство будет опущено.
- Name
  emission
  Type
  string
  Description
  Загружаемый URL-адрес изображения карты эмиссии.
  Если задача создана с enable_pbr: false, или ai_model — это meshy-5, meshy-7 или 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 (кредиты возвращаются при неудаче).

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

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