Image to 3D API

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

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

Создание задачи Image to 3D

Этот эндпоинт позволяет создать новую задачу Image to 3D. Обратитесь к Объект задачи Image to 3D, чтобы узнать, какие свойства включены в объект задачи Image to 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-t1 или 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.
- meshy-t1: старая низкополигональная модель; не поддерживает установку количества лиц с 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 для управления процессом текстурирования. Максимум 600 символов.
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, 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: Генерирует модель в позе А.
- 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, служба использует AI vision для автоматической оценки реальной высоты объекта и изменения размера модели соответствующим образом. Начало координат по умолчанию будет bottom, если только origin_at явно не установлен.
Name
alpha_thumbnail
Type
boolean
по умолчанию false
Description
Когда установлено в true, задача дополнительно рендерит preview с прозрачным фоном (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 только что созданной задачи Image to 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 истинно.
Name
401 - Unauthorized
Description
Ошибка аутентификации. Проверьте свой API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
429 - Too Many Requests
Description
Вы превысили свое ограничение частоты.

Запрос

POST

/openapi/v1/image-to-3d

# Простой запрос с обязательными параметрами
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>"
  }'

# С ремешингом, PBR и A-позой
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"]
  }'

Ответ

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

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

Получение задачи Image to 3D

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

Параметры

Name
id
Type
path
Description
Уникальный идентификатор задачи Image to 3D для получения.

Возвращает

Ответ содержит объект задачи Image to 3D. Проверьте раздел Объект задачи Image to 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

Удаление задачи Image to 3D

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

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

Name
id
Type
path
Description
ID задачи Image to 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}"

Ответ

// Возвращает 200 Ok при успехе.

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

Список задач Image to 3D

Этот эндпоинт позволяет получить список задач Image to 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: Сортировка по времени создания по убыванию.

Возвращает

Возвращает список объектов Объект задачи Image to 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

Потоковая передача задачи Image to 3D

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

Параметры

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

Возвращает

Возвращает поток объектов Объект задачи Image to 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}"

Ответный поток

// Пример события ошибки
event: error
data: {
  "status_code": 404,
  "message": "Задача не найдена"
}

// Примеры событий сообщения иллюстрируют progress задачи.
// Для задач PENDING или IN_PROGRESS поток ответа не будет включать все поля.
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
}

Объект задачи Image to 3D

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

Свойства

Name
id
Type
string
Description
Уникальный идентификатор задачи. Мы используем k-сортируемый UUID для идентификаторов задач как деталь реализации, вы не должны делать никаких предположений о формате идентификатора.
Name
type
Type
string
Description
Тип задачи Image to 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 и прозрачный preview успешно отрендерен; в противном случае это поле опускается.
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 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
Массив объектов 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 (кредиты возвращаются при неудаче).

Пример объекта задачи Image to 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
}