Image to 3D API

Превратите изображение в 3D-модель, с текстурами или без них, в выбранных вами форматах. Отправьте изображение или используйте результат задачи Текст в изображение или Изображение в изображение.

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

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

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

Request

POST

/openapi/v1/image-to-3d

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

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

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

Response

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

Параметры

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

Name
image_url
Type
string
Обязательный
Description
Обязателен, если не отправлен input_task_id. Изображение для преобразования в 3D-модель, в виде публичного URL или base64-кодированного data URI, например data:image/jpeg;base64,<ваши base64-кодированные данные изображения>. Если отправлены оба параметра, Meshy использует input_task_id.
Изображение должно быть файлом JPG, JPEG, PNG или WebP размером не более 20 МБ, не менее 32 пикселей по каждой стороне и не более 178 956 970 пикселей (ширина × высота).

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

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

Name
texture_model
Type
string
по умолчанию depends on ai_model
Description
ИИ-модель, которая текстурирует 3D-модель в рамках той же задачи. Если не указать, используется модель текстурирования по умолчанию для вашей ai_model. Это не влияет на стоимость в кредитах.
Доступные значения:
- meshy-7: Meshy 7, с PBR-картами и текстурами до 8K
- meshy-n1: Meshy N1, 2K-текстура базового цвета только по референсным изображениям
- meshy-6-lite: Meshy 6 Lite, 2K-текстура по минимальной цене
- meshy-6: Meshy 6, только как значение по умолчанию для ai_model: meshy-6
Каждая ai_model принимает meshy-7, meshy-n1 и meshy-6-lite. Опция, не поддерживаемая выбранной моделью текстурирования, возвращает 400. При meshy-n1 сгенерированная модель с более чем 7 999 999 треугольниками приводит к сбою задачи, и Meshy возвращает её кредиты. При should_texture: false Meshy игнорирует texture_model, но неизвестное значение всё равно возвращает 400.
О том, что делает каждая модель текстурирования и какую выбрать, см. Модели.
Name
enable_pbr
Type
boolean
по умолчанию false
Description
Создавать ли также PBR-карты (металличность, шероховатость и нормали) помимо базового цвета. true требует should_texture: true и возвращает 400 при should_texture: false. При texture_model: meshy-n1 значение true возвращает 400.
Модель текстурирования Meshy 6 также создаёт карту излучения (emission), кроме случая texture_resolution: 8k.
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
Изображение, направляющее создание текстуры, в виде публичного URL или base64-кодированного data URI, например data:image/jpeg;base64,<ваши base64-кодированные данные изображения>. Изображение должно быть файлом JPG, JPEG, PNG или WebP размером не более 20 МБ, не менее 32 пикселей по каждой стороне и не более 178 956 970 пикселей (ширина × высота).
Meshy направляет создание текстуры только по одному из параметров: texture_prompt или texture_image_url. Если отправлены оба, Meshy использует texture_prompt. О стоимости текстурирования в кредитах см. Цены.
При texture_model: meshy-n1 Meshy текстурирует с использованием этого изображения как вида спереди, либо входного изображения, если этот параметр не указан.
Текстурирование по изображению может работать плохо, если форма изображения сильно отличается от геометрии 3D-модели.

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: децимированная треугольная сетка
Вывод Smart Topology состоит только из треугольников, поэтому quad вместе с meshy-t2 или meshy-t2.5 возвращает 400. При texture_model: meshy-n1 значение quad возвращает 400, когда модель подвергается ремешингу, что meshy-6-lite делает по умолчанию.
Name
decimation_mode
Type
integer
Description
Адаптивное число граней по уровню. При установке этого параметра Meshy игнорирует target_polycount.
Доступные значения:
- 1: ультра
- 2: высокий
- 3: средний
- 4: низкий
Name
save_pre_remeshed_model
Type
boolean
по умолчанию false
Description
Сохранять ли также GLB-файл модели в том виде, в каком она была до этапа ремешинга. Meshy возвращает его в model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
Целевое количество граней. Результат может отличаться от целевого значения в зависимости от геометрии модели.
Этот параметр применяется в двух разных случаях:
- Ремешинг: когда should_remesh равен true для модели standard, Meshy децимирует сетку примерно до этого числа. Если задан decimation_mode, Meshy использует его и игнорирует target_polycount.
- Smart Topology: когда model_type равен smart-topology, а ai_model — meshy-t2 или meshy-t2.5, Meshy создаёт модель с этим числом граней. Ремешинг не выполняется, и should_remesh не требуется.
Диапазон и значение по умолчанию зависят от случая:
Случай Диапазон По умолчанию
Ремешинг 100–300000 30000
meshy-t2 100–15000 4000
meshy-t2.5 100–30000 15000
Значение вне диапазона возвращает 400.

Случай	Диапазон	По умолчанию
Ремешинг	`100`–`300000`	`30000`
`meshy-t2`	`100`–`15000`	`4000`
`meshy-t2.5`	`100`–`30000`	`15000`

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
surface_mode
Type
string
⚠ устаревший
Description
Используйте вместо этого ai_model. Этот параметр не влияет на результат, так как выбиравшийся им способ генерации модели больше не используется.
Допустимые значения: organic и hard. Любое другое значение возвращает 400.
Name
image_enhancement
Type
boolean
по умолчанию true
Description
Оптимизировать ли входное изображение перед генерацией. false сохраняет исходный внешний вид входного изображения без какой-либо стилевой обработки.
Работает только с meshy-6, meshy-7.1 или latest. При meshy-6-lite или model_type: smart-topology возвращает 400.
Name
remove_lighting
Type
boolean
по умолчанию true
Description
Удалять ли блики и тени из текстуры базового цвета. Результат получается чище и лучше подходит для использования с собственным освещением.
Действует только с моделью текстурирования Meshy 6, а модель текстурирования, не поддерживающая эту функцию, возвращает 400 при значении true. При model_type: smart-topology, либо при ai_model: meshy-6-lite и её модели текстурирования по умолчанию, отправка этого параметра возвращает 400.
Name
moderation
Type
boolean
по умолчанию false
Description
Проверять ли эти входные данные на наличие вредоносного контента перед генерацией:
- image_url
- texture_image_url
- texture_prompt
Если Meshy обнаруживает вредоносный контент, запрос возвращает 400, и Meshy не создаёт задачу.
Name
target_formats
Type
string[]
Description
Форматы файлов для создания. Meshy создаёт и возвращает только перечисленные вами форматы, что может сократить время выполнения задачи. Если параметр не указан, Meshy создаёт все форматы, кроме 3mf, который вы получите только если укажете его явно.
Доступные значения:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
по умолчанию false
Description
Оценивать ли реальную высоту объекта с помощью ИИ-зрения и масштабировать модель под неё. Meshy помещает начало координат внизу, если не задан origin_at.
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 секунд.

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

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

Возвращаемые данные

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

Варианты сбоя

Name
400 - Bad Request
Description
Запрос не может быть выполнен. Сообщение об ошибке указывает, в чём проблема. Например:
- Отсутствует параметр: не отправлен ни image_url, ни input_task_id.
- Недопустимая входная задача: input_task_id не является задачей Текст в изображение или Изображение в изображение со статусом SUCCEEDED, выдавшей ровно одно изображение.
- Недопустимый формат изображения: изображение image_url не является файлом JPG, JPEG, PNG или WebP.
- Недоступный URL: Meshy не может загрузить изображение image_url, так как URL возвращает 404 или превышено время ожидания.
- Слишком большое изображение: изображение image_url или texture_image_url превышает 20 МБ.
- Недопустимый размер изображения: изображение image_url или texture_image_url имеет сторону короче 32 пикселей или более 178 956 970 пикселей (ширина × высота).
- Недопустимый data URI: строка base64 имеет неверный формат.
- Недопустимая комбинация параметров: enable_pbr равен true, а should_texture равен false.
- Неподдерживаемая модель для Ultra: geometry_resolution равен 2k или 4k при ai_model, который не может это выполнить.
- Неподдерживаемая модель для параметров изображения: один из вариантов:
  - image_enhancement был отправлен вместе с ai_model: "meshy-6-lite" или model_type: "smart-topology".
  - remove_lighting был отправлен вместе с model_type: "smart-topology", либо с ai_model: "meshy-6-lite" и её моделью текстурирования по умолчанию.
- Недопустимая модель текстурирования: texture_model не является одним из доступных значений.
- Модель текстурирования недоступна: texture_model равен meshy-6 при ai_model, отличной от meshy-6. Отправьте meshy-7, meshy-n1 или meshy-6-lite, либо не указывайте этот параметр.
- Неподдерживаемая опция для модели текстурирования: запрос запрашивает у модели текстурирования опцию, которую она не поддерживает, например enable_pbr: true с meshy-n1 или текстуру 4k с meshy-6-lite. См. Модели.
Исправьте запрос и отправьте его снова. См. Ошибки.
Name
401 - Unauthorized
Description
API-ключ отсутствует или недействителен. Проверьте заголовок Authorization.
Name
402 - Payment Required
Description
Например:
- Недостаточно кредитов: на счёте недостаточно кредитов для этой задачи, либо достигнут лимит кредитов. Проверьте баланс кредитов и повторите попытку.
- Бесплатный план: для создания задачи требуется платный план. Обновите свой план в настройках подписки, затем повторите попытку.
Name
403 - Forbidden
Description
Модерация контента заблокировала prompt или входное изображение. Измените входные данные и повторите попытку.
Name
404 - Not Found
Description
input_task_id не соответствует ни одной из ваших задач. Проверьте ID задачи и отправьте запрос снова.
Name
429 - Too Many Requests
Description
Превышено ограничение частоты запросов. Подождите и повторите попытку. См. Ограничения частоты.

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

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

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

Request

GET

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

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

Response

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

Параметры

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

Возвращает

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

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

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

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

Request

DELETE

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

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

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task 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/image-to-3d

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

Возвращает список ваших задач Изображение в 3D.

Request

GET

/openapi/v1/image-to-3d

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

Response

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

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

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

Request

GET

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

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

Response Stream

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

// Message event examples illustrate task progress.
// 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": "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": null,
  "consumed_credits": 30
}

Параметры

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

Возвращает

Поток объектов задачи Изображение в 3D в формате Server-Sent Events.

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

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

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

Свойства

Example Image to 3D Task Object

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

Name
id
Type
string
Description
ID задачи. Рассматривайте его как непрозрачную строку и не полагайтесь на её формат.
Name
type
Type
string
Description
Тип задачи, всегда 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-адрес для скачивания предварительного изображения 3D-модели. Когда присутствует thumbnail_urls, это то же изображение, что и thumbnail_urls.front. Meshy сохраняет это поле для обратной совместимости.
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_url
Type
string
Description
URL-адрес для скачивания изображения, по которому создавалась текстура.
Name
ultra_mode
Type
boolean
⚠ устаревший
Description
Используйте вместо этого geometry_resolution.
Name
geometry_resolution
Type
string
Description
Уровень Ultra, с которым выполнялась задача: 2k или 4k. Задача уровня standard не включает это поле.
Name
progress
Type
integer
Description
Насколько выполнена задача, в процентах. Значение равно 0, пока задача не началась, и 100, когда она завершается успешно.
Name
started_at
Type
timestamp
Description
Время начала задачи, в миллисекундах 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
Карты текстур, сгенерированные задачей, в виде массива объектов. Обычно содержит один объект со следующими полями:
- 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-адрес для скачивания карты эмиссии. Meshy включает её только если вы создали задачу со всеми следующими параметрами:
  
  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 возвращает кредиты, если задача завершается неудачно.