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,<your base64-encoded image data>. Якщо надіслати обидва, 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
AI-модель, що генерує 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: чистіша topology та природно розділені частини
- 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
AI-модель, що текстурує 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 map), окрім випадку 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,<your base64-encoded image data>. Зображення має бути файлом 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: ultra
- 2: high
- 3: medium
- 4: low
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
Чи оцінювати реальну висоту об'єкта за допомогою AI-зору та змінювати розмір моделі відповідно до неї. 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

List Image to 3D tasks

Повертає список ваших завдань Зображення у 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 моделі із зображення. Він містить статус, progress та файли моделі, коли завдання завершується успішно.

Властивості

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. Для завдання FAILED дорівнює 0, оскільки Meshy повертає кредити, коли завдання завершується невдало.