API Мульти-изображение в 3D

Создайте 3D-модель на основе от одного до четырёх изображений одного и того же объекта, снятых под разными углами.

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

Создание задачи Мульти-изображение в 3D

Создаёт задачу Мульти-изображение в 3D. Задача выполняется в фоновом режиме. О том, сколько обычно занимает выполнение задачи, см. Время обработки. Поля, которые содержит задача, описаны в разделе Объект задачи Мульти-изображение в 3D.

Request

POST

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

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

# With Ultra 2K geometry, PBR texturing, and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "geometry_resolution": "2k",
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input images, the first as the front view
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your front view image url or base64-encoded data URI>",
      "<your back view image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "texture_model": "meshy-n1"
  }'

Response

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

Параметры

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

Name
image_urls
Type
array
Обязательный
Description
Обязателен, если вы не отправляете input_task_id. От одного до четырёх изображений, каждое в виде публичного URL или data URI, например data:image/jpeg;base64,<ваши данные изображения в формате base64>. Если вы отправили оба параметра, Meshy использует input_task_id.
Каждое изображение должно быть файлом .jpg, .jpeg, .png или .webp размером не более 20 МБ, не менее 32 пикселей по каждой стороне и не более 178 956 970 пикселей (ширина × высота). Если отправлено более четырёх изображений, возвращается 400.
Для наилучшего результата изображения должны показывать один и тот же объект с разных ракурсов. В meshy-7.1 или latest Meshy использует первое изображение как вид спереди, а порядок остальных значения не имеет.

Name
ai_model
Type
string
по умолчанию latest
Description
AI-модель, генерирующая 3D-модель.
Доступные значения:
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7: устаревшее, отправляйте вместо него meshy-7.1
Name
geometry_resolution
Type
string
по умолчанию standard
Description
Сколько детализации геометрии нужно сгенерировать.
Доступные значения:
- standard
- 2k: запускает проход Ultra с разрешением 2048³. Требует meshy-7.1, latest или устаревший meshy-7.
Name
ultra_mode
Type
boolean
⚠ устаревший
по умолчанию false
Description
Вместо этого отправляйте geometry_resolution. ultra_mode: true эквивалентно geometry_resolution: "2k".
Name
should_texture
Type
boolean
по умолчанию true
Description
Создавать ли текстуры. При true возвращается модель с текстурами, при false этап текстурирования пропускается и возвращается сетка без текстур.

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

Name
texture_model
Type
string
по умолчанию depends on ai_model
Description
AI-модель, которая текстурирует 3D-модель с нескольких ракурсов в рамках одной задачи. Если не указать, используется текстурная модель по умолчанию для вашего ai_model. Это не влияет на стоимость в кредитах.
Доступные значения:
- meshy-7: Meshy 7, с PBR-картами и текстурами до 8K
- meshy-n1: Meshy N1, базовая цветовая текстура 2K только по референсным изображениям
Каждая ai_model поддерживает оба варианта. Запрос с текстурированием и meshy-6 или meshy-6-lite возвращает 400, как и опция, не поддерживаемая выбранной текстурной моделью. При should_texture: false Meshy игнорирует texture_model, но неизвестное значение всё равно вернёт 400.
При meshy-n1 Meshy текстурирует на основе texture_image_urls или texture_image_url, либо, если ни один из них не отправлен, на основе входных изображений. Первое изображение — вид спереди. Если сгенерированная модель превышает 7 999 999 треугольников, задача завершается ошибкой, и Meshy возвращает кредиты.
О том, что делает каждая текстурная модель и какую выбрать, см. в разделе Модели.
Name
enable_pbr
Type
boolean
по умолчанию false
Description
Генерировать ли дополнительно карты металличности, шероховатости и нормалей, помимо базового цвета. Текстурная модель Meshy 6 также генерирует карту излучения (emission), кроме как при texture_resolution: 8k. При texture_model: meshy-n1 значение true возвращает 400.
Name
texture_resolution
Type
string
по умолчанию 2k
Description
Размер базовой цветовой текстуры. Больший размер передаёт больше деталей поверхности.
Доступные значения:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k и 8k требуют текстурную модель Meshy 7 или Meshy 6 и с остальными возвращают 400. При 8k Meshy не генерирует карту излучения.
Name
hd_texture
Type
boolean
⚠ устаревший
по умолчанию false
Description
Вместо этого отправляйте texture_resolution. hd_texture: true эквивалентно texture_resolution: "4k". Если отправлены оба, Meshy использует texture_resolution.
Name
texture_prompt
Type
string
Description
Текст, определяющий текстуру, до 800 символов. Более длинный текст возвращает 400. При texture_model: meshy-n1 отправка этого параметра возвращает 400.
Name
texture_image_url
Type
string
Description
Одно 2D-изображение, определяющее текстуру, в виде публичного URL или data URI, например data:image/jpeg;base64,<ваши данные изображения в формате base64>. Изображение должно быть файлом .jpg, .jpeg, .png или .webp размером не более 20 МБ, не менее 32 пикселей по каждой стороне и не более 178 956 970 пикселей (ширина × высота).
Если отправлены оба параметра, texture_image_url и texture_prompt, Meshy использует texture_prompt. При texture_model: meshy-n1 Meshy текстурирует на основе этого изображения как вида спереди.
Текстура может получиться не очень хорошо, если форма на изображении сильно отличается от 3D-модели.
Name
texture_image_urls
Type
string[]
Description
От одного до четырёх изображений объекта с разных ракурсов, определяющих текстуру. Meshy использует первое изображение как вид спереди. Порядок остальных ракурсов (слева, сзади, справа) значения не имеет.
Каждое изображение подчиняется тем же правилам, что и texture_image_url. Это публичный URL или data URI в формате .jpg, .jpeg, .png или .webp, размером не более 20 МБ, не менее 32 пикселей по каждой стороне и не более 178 956 970 пикселей (ширина × высота).
Эти изображения определяют только текстуру и не зависят от image_urls. Оба списка могут содержать разные изображения и разное их количество.
texture_image_urls требует текстурную модель Meshy 7 или Meshy N1. Отправляйте его вместе с одним из следующих:
- ai_model со значением meshy-7.1, latest или устаревшим meshy-7
- texture_model со значением meshy-7 или meshy-n1
Нельзя отправлять его вместе с texture_image_url или texture_prompt.

Name
should_remesh
Type
boolean
по умолчанию true (meshy-6-lite), false (other models)
Description
Выполнять ли ремешинг модели после генерации. Для максимального качества 3D-модели установите значение false.

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

Name
topology
Type
string
по умолчанию triangle
Description
Тип граней модели после ремешинга.
Доступные значения:
- quad: сетка с преобладанием четырёхугольников
- triangle: уменьшенная треугольная сетка
При texture_model: meshy-n1 значение quad возвращает 400, если модель подвергается ремешингу, что по умолчанию делает meshy-6-lite.
Name
target_polycount
Type
integer
по умолчанию 30000
Description
Целевое количество граней, от 100 до 300000. Результат может отличаться от целевого значения в зависимости от геометрии модели. Значение вне диапазона возвращает 400.
Name
decimation_mode
Type
integer
Description
Адаптивное количество граней по уровням. При установке этого параметра Meshy игнорирует target_polycount.
Доступные значения:
- 1: ультра
- 2: высокий
- 3: средний
- 4: низкий
Name
save_pre_remeshed_model
Type
boolean
по умолчанию false
Description
Сохранять ли также GLB-файл состояния до ремешинга, который возвращается в model_urls.pre_remeshed_glb.

Name
symmetry_mode
Type
string
⚠ устаревший
по умолчанию auto
Description
Не указывайте этот параметр. Он не влияет на результат.
Доступные значения:
- 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 сохраняется точный вид входных изображений, без стилевой обработки. Поддерживается только с meshy-6, meshy-7.1 или latest. Отправка этого параметра с meshy-6-lite возвращает 400.
Name
remove_lighting
Type
boolean
по умолчанию true
Description
Удалять ли блики и тени из базовой цветовой текстуры. Более чистый результат лучше смотрится под собственным освещением вашей сцены. Используется только текстурной моделью Meshy 6, а при texture_resolution: 8k освещение удаляется всегда. При texture_model: meshy-n1 значение true возвращает 400. При ai_model: meshy-6-lite и её текстурной модели по умолчанию отправка этого параметра возвращает 400.
Name
moderation
Type
boolean
по умолчанию false
Description
Проверять ли входные данные на вредоносный контент. Meshy проверяет каждое входное изображение, texture_image_url или каждое изображение в texture_image_urls, а также текст в texture_prompt. Если Meshy обнаруживает вредоносный контент, запрос возвращает 400, и Meshy не создаёт задачу.
Name
target_formats
Type
string[]
Description
Форматы 3D-файлов для генерации. Meshy генерирует и возвращает только перечисленные форматы, что может сократить время выполнения задачи.
Доступные значения:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Если параметр не указан, Meshy генерирует все форматы, кроме 3mf. Формат 3mf Meshy генерирует только если он явно указан в списке.
Name
auto_size
Type
boolean
по умолчанию false
Description
Оценивать ли реальную высоту объекта с помощью компьютерного зрения ИИ и масштабировать модель под неё. Meshy помещает начало координат внизу, если вы не укажете origin_at.

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

Name
origin_at
Type
string
по умолчанию bottom
Description
Куда поместить начало координат модели: bottom (внизу) или center (в центре).

Name
alpha_thumbnail
Type
boolean
по умолчанию false
Description
Рендерить ли также превью с прозрачным фоном (RGBA), которое возвращается в alpha_thumbnail_url при получении задачи. thumbnail_url при этом не меняется.
Name
multi_view_thumbnails
Type
boolean
по умолчанию false
Description
Рендерить ли также превью спереди, справа, сзади и слева, которые возвращаются в thumbnail_urls при получении задачи. thumbnail_url при этом не меняется и по-прежнему показывает вид спереди. Это добавляет к задаче около 5 секунд.

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

Поле result ответа содержит ID новой задачи Мульти-изображение в 3D.

Режимы сбоя

Name
400 - Bad Request
Description
Запрос не может быть выполнен. Сообщение об ошибке указывает, в чём проблема. Например:
- Missing parameter: не был отправлен ни image_urls, ни input_task_id.
- Invalid input task: input_task_id не является задачей Текст в изображение или Изображение в изображение (в том числе мультивидом) со статусом SUCCEEDED.
- Invalid image count: image_urls или texture_image_urls содержит не от 1 до 4 изображений.
- Invalid image format: изображение в image_urls имеет неподдерживаемый формат.
- Conflicting texture inputs: texture_image_urls был отправлен вместе с texture_image_url, с texture_prompt или с should_texture: false.
- Unsupported model for multi-view texture: texture_image_urls был отправлен с ai_model равным meshy-6 или meshy-6-lite, при этом texture_model не равен meshy-7 или meshy-n1.
- Unreachable URL: Meshy не может загрузить изображение из image_urls или texture_image_urls.
- Image too large: изображение в image_urls, texture_image_url или texture_image_urls превышает 20 МБ.
- Invalid image size: сторона изображения в image_urls, texture_image_url или texture_image_urls меньше 32 пикселей или превышает 178 956 970 пикселей (ширина × высота).
- Unsupported resolution for multi-image input: geometry_resolution равен "4k", что не поддерживается данным эндпоинтом. Используйте 2k или standard.
- Unsupported model for image options: image_enhancement был отправлен с ai_model: "meshy-6-lite", либо remove_lighting был отправлен с ai_model: "meshy-6-lite" и её текстурной моделью по умолчанию.
- Invalid texture model: texture_model не является допустимым именем текстурной модели.
- Texture model not available: в запросе с текстурированием был отправлен texture_model равный meshy-6 или meshy-6-lite. Мульти-изображение в 3D принимает только текстурные модели, текстурирующие с нескольких ракурсов. Отправьте meshy-7 или meshy-n1, либо не указывайте texture_model.
- Unsupported option for the texture model: запрос запрашивает у текстурной модели опцию, которую она не поддерживает, например enable_pbr: true с meshy-n1 или текстуру 4k с meshy-6-lite. См. Модели.
Исправьте запрос и отправьте его снова. См. Ошибки.
Name
401 - Unauthorized
Description
API-ключ отсутствует или недействителен. Проверьте заголовок Authorization.
Name
402 - Payment Required
Description
Например:
- Insufficient credits: на счёте недостаточно кредитов для выполнения этой задачи, либо аккаунт достиг лимита кредитов. Проверьте баланс кредитов, затем повторите попытку.
- Free plan: для создания задачи требуется платный план. Обновите свой план в настройках подписки, затем повторите попытку.
Name
403 - Forbidden
Description
Модерация контента заблокировала prompt или входное изображение. Измените входные данные, затем повторите попытку.
Name
404 - Not Found
Description
input_task_id не соответствует ни одной из ваших задач. Проверьте ID задачи, затем отправьте запрос снова.
Name
429 - Too Many Requests
Description
Вы превысили ограничение частоты запросов. Подождите, затем повторите попытку. См. Ограничения частоты.

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

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

Возвращает задачу Мульти-изображение в 3D по её ID.

Request

GET

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

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Параметры

Name
id
Type
path
Description
ID задачи из ответа при создании.

Возвращает

Объект задачи Мульти-изображение в 3D.

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

Удаление задачи Мульти-изображение в 3D

Безвозвратно удаляет задачу Мульти-изображение в 3D, включая её модели и данные. Отменить удаление нельзя.

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/multi-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 keeps 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."
}

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

Name
id
Type
path
Description
ID задачи, которую нужно удалить.

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

Удаление задачи со статусом PENDING возвращает кредиты, потраченные на её создание.

Задачу со статусом IN_PROGRESS удалить нельзя. Запрос вернёт 409 Conflict, и задача продолжит выполняться. Meshy не возвращает кредиты за задачу, которая уже начала выполняться, поэтому удаление такой задачи означало бы потерю и кредитов, и результата. Дождитесь, пока она перейдёт в статус SUCCEEDED, FAILED или CANCELED, и только после этого удаляйте её.

Удаление задачи в финальном статусе (SUCCEEDED, FAILED или CANCELED) не возвращает потраченные на неё кредиты.

Возвращает

200 OK, когда задача удалена, или 409 Conflict, когда задача имеет статус IN_PROGRESS.

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

Список задач Мульти-изображение в 3D

Возвращает список ваших задач Мульти-изображение в 3D.

Request

GET

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

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "multi-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"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 30
  }
]

Параметры

Name
page_num
Type
integer
по умолчанию 1
Description
Номер страницы для возврата, вплоть до 255. Большее значение вернёт 400.
Name
page_size
Type
integer
по умолчанию 10
Description
Количество задач на странице, вплоть до 100.
Name
sort_by
Type
string
Description
Порядок сортировки.
Доступные значения:
- +created_at: сначала старые
- -created_at: сначала новые

Возвращает

Постраничный список объектов задачи Мульти-изображение в 3D.

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

Трансляция задачи Мульти-изображение в 3D

Транслирует обновления задачи Мульти-изображение в 3D в виде Server-Sent Events (SSE).

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/multi-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.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Параметры

Name
id
Type
path
Description
ID задачи из ответа на создание.

Возвращает

Поток объектов задачи Мульти-изображение в 3D в виде Server-Sent Events.

Каждое событие содержит полный объект задачи в том же виде, в каком его возвращает эндпоинт Get. Пока задача находится в статусе PENDING или IN_PROGRESS, поля результата ещё не имеют значений.

Объект задачи Мульти-изображение в 3D

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

Свойства

Example Multi-Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Name
id
Type
string
Description
ID задачи. Воспринимайте его как непрозрачную строку и не полагайтесь на её формат.
Name
type
Type
string
Description
Тип задачи, всегда multi-image-to-3d.
Name
model_urls
Type
object
Description
URL-адреса для скачивания сгенерированной 3D-модели, по одному на каждый формат файла. Для формата, который задача не сгенерировала, ключ отсутствует, а не содержит пустую строку.
- 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. Присутствует только когда target_formats включает 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Файл 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 и Meshy отрендерил прозрачное превью.
Name
thumbnail_urls
Type
object
Description
URL-адреса для скачивания превью 3D-модели с четырёх сторон. Каждый из них — это подписанный URL на PNG размером 512×512, отрендеренный с теми же материалами и освещением, что и thumbnail_url. Вы можете использовать их для предпросмотра модели под разными углами без скачивания GLB.
Присутствует только если вы создали задачу с multi_view_thumbnails: true и задача достигла статуса SUCCEEDED. Задача, созданная без multi_view_thumbnails: true, не содержит этого поля.
- 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_urls
Type
string[]
Description
URL-адреса для скачивания референсных изображений текстуры, с которыми вы создали задачу, в том порядке, в котором вы их отправили. Присутствует только если вы создали задачу с texture_image_urls.
Name
ultra_mode
Type
boolean
⚠ устаревший
Description
Используйте вместо этого geometry_resolution.
Name
geometry_resolution
Type
string
Description
Уровень Ultra, с которым выполнялась задача, равный 2k. Задача уровня standard не содержит этого поля.
Name
progress
Type
integer
Description
Насколько выполнена задача, в процентах. Значение 0, пока задача не началась, и 100, когда она завершается успешно.
Name
started_at
Type
timestamp
Description
Время начала задачи, в миллисекундах Unix. Значение 0, пока задача не началась.
Name
created_at
Type
timestamp
Description
Время создания задачи, в миллисекундах Unix.
Name
expires_at
Type
timestamp
Description
Время истечения срока действия результатов задачи, в миллисекундах Unix.
Name
finished_at
Type
timestamp
Description
Время завершения задачи, в миллисекундах Unix. Значение 0, пока задача не завершится.
Name
status
Type
string
Description
Статус задачи, один из PENDING, IN_PROGRESS, SUCCEEDED, FAILED или CANCELED.
Name
texture_urls
Type
array
Description
URL-адреса для скачивания карт текстур, сгенерированных задачей, в виде массива объектов. Обычно содержит один объект. Каждый объект содержит следующие поля:
- 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
  Карта излучения. Включается только если вы создали задачу со всем следующим:
  
  ai_model: meshy-6, с его текстурной моделью по умолчанию
  
  enable_pbr: true
  
  texture_resolution со значением 2k или 4k
Name
preceding_tasks
Type
integer
Description
Количество задач перед этой в очереди. Значение имеет смысл только пока задача находится в статусе PENDING.
Name
task_error
Type
object
Description
Детали ошибки, если задача завершилась неудачно. Равно null, если статус не FAILED. См. Ошибки.
Name
consumed_credits
Type
integer
Description
Количество кредитов, потраченных задачей. Присутствует, когда статус PENDING, IN_PROGRESS или SUCCEEDED. Равно 0 для задачи со статусом FAILED, потому что Meshy возвращает кредиты, когда задача завершается неудачно.