API Зображення у 3D

API Зображення у 3D — це функція, яка дозволяє вам інтегрувати можливості Meshy із перетворення зображень у 3D у ваш власний застосунок. У цьому розділі ви знайдете всю інформацію, яка потрібна для початку роботи з цим API.

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

Create an Image to 3D Task

Ця кінцева точка дозволяє створити нове завдання Зображення у 3D. Див. Об'єкт завдання Зображення у 3D, щоб дізнатися, які властивості включені в об'єкт завдання Зображення у 3D.

Завдання виконується у фоновому режимі. Про те, скільки це зазвичай триває, див. Час обробки.

Параметри

Потрібен лише один з параметрів input_task_id або image_url. Якщо вказано обидва, пріоритет має input_task_id.

Name
input_task_id
Type
string
Обов'язковий
Description
ID завершеного завдання генерації зображення, результат якого слід використати як вхідне зображення. Це завдання має бути одним із наступних: Текст у зображення або Зображення у зображення. Крім того, воно має бути виконане через API, мати статус SUCCEEDED та створювати рівно одне зображення.

Name
image_url
Type
string
Обов'язковий
Description
Надайте зображення для використання Meshy при створенні моделі. Наразі підтримуються формати .jpg, .jpeg, .png та .webp.
Максимальний розмір файлу: 20 МБ.
Існує два способи надати зображення:
- Загальнодоступне URL-посилання: URL-адреса, доступна з публічного інтернету.
- Data URI: Base64-кодований data URI зображення. Приклад data URI: data:image/jpeg;base64,<ваші base64-кодовані дані зображення>.

Name
model_type
Type
string
за замовчуванням standard
Description
Вкажіть тип генерації 3D-сітки.
Доступні значення:
- standard: Звичайна високодеталізована генерація 3D-сітки.
- smart-topology: Виберіть модель Smart Topology за допомогою ai_model (meshy-t2).
- lowpoly (застаріле, виводиться з використання 30 жовтня 2026 року): Генерує низькополігональну сітку, оптимізовану для чистіших полігонів. Натомість рекомендуємо Meshy T2: smart-topology з meshy-t2.
Коли вибрано smart-topology, параметри should_remesh, save_pre_remeshed_model та decimation_mode ігноруються, і приймається лише topology: triangle.
lowpoly буде виведено з використання 30 жовтня 2026 року. Після цієї дати запити з model_type: "lowpoly" повертатимуть помилку. Рекомендуємо перейти на Meshy T2 (model_type: "smart-topology" з ai_model: "meshy-t2"). Коли вибрано lowpoly, параметри ai_model, topology, target_polycount, should_remesh та save_pre_remeshed_model ігноруються.
Name
ai_model
Type
string
за замовчуванням latest
Description
ID моделі для використання. Доступні значення залежать від model_type.
Стандартна генерація (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (застаріле): натомість використовуйте meshy-7.1.
Генерація Smart Topology (model_type: smart-topology):
- meshy-t2 (за замовчуванням): модель Smart Topology — чистіша topology, природно розділені частини, вихід у вигляді трикутників та кількість граней, яку можна встановити за допомогою target_polycount.
Name
geometry_resolution
Type
string
за замовчуванням standard
Description
Етап генерації геометрії. 2k запускає Ultra-прохід у роздільній здатності 2048³; 4k запускає його у 4096³ для найдетальнішої поверхні.
Доступні значення: standard, 2k, 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
Визначає, чи генеруються текстури. Встановлення значення false пропускає етап текстурування, надаючи сітку без текстур.

Застосовується лише коли should_texture = true

Name
enable_pbr
Type
boolean
за замовчуванням false
Description
Генерувати PBR-карти (металевість, шорсткість, нормалі) на додаток до базового кольору. Карта випромінювання (emission) також включається, коли ai_model має значення meshy-6, за винятком texture_resolution: 8k. meshy-6-lite, meshy-7.1, meshy-t2 та latest не створюють карту випромінювання.
Name
texture_resolution
Type
string
за замовчуванням 2k
Description
Роздільна здатність текстури базового кольору. Одне зі значень 2k (2048×2048), 4k (4096×4096) або 8k (8192×8192). Вища роздільна здатність дає більше деталей поверхні.
4k та 8k недоступні з ai_model meshy-6-lite. При 8k карта випромінювання не створюється.
Name
hd_texture
Type
boolean
⚠ застарілий
за замовчуванням false
Description
Натомість використовуйте texture_resolution — еквівалентно texture_resolution: "4k". Якщо встановлено обидва, пріоритет має texture_resolution.
Name
texture_prompt
Type
string
Description
Надайте текстовий prompt для керування процесом текстурування. Максимум 800 символів.
Name
texture_image_url
Type
string
Description
Надайте 2D-зображення для керування процесом текстурування. Наразі підтримуються формати .jpg, .jpeg, .png та .webp.
Максимальний розмір файлу: 20 МБ.
Існує два способи надати зображення:
- Загальнодоступне URL-посилання: URL-адреса, доступна з публічного інтернету
- Data URI: Base64-кодований data URI зображення. Приклад data URI: data:image/jpeg;base64,<ваші base64-кодовані дані зображення>
Текстурування за зображенням може працювати неоптимально, якщо існують суттєві відмінності в геометрії між оригінальним асетом та завантаженим зображенням. Для керування процесом текстурування можна використати лише один із параметрів texture_image_url або texture_prompt. Якщо вказано обидва параметри, за замовчуванням для текстурування моделі використовуватиметься texture_prompt. Текстурування як за допомогою тексту, так і зображення коштуватиме 10 кредитів за завдання.

Name
should_remesh
Type
boolean
за замовчуванням false (Meshy 6 and Meshy 7 models), true (others)
Description
Керує тим, чи вмикати етап ремешу. Для отримання найякіснішої моделі рекомендуємо встановити should_remesh у значення false.

Застосовується лише коли should_remesh = true

Name
topology
Type
string
за замовчуванням triangle
Description
Вкажіть topology створеної моделі.
Доступні значення:
- quad: Генерувати сітку з переважанням чотирикутників.
- triangle: Генерувати децимовану трикутну сітку.
Вихід Smart Topology — лише трикутний. Запит quad разом з ai_model: meshy-t2 повертає помилку.
Name
decimation_mode
Type
integer
Description
Увімкнути адаптивну децимацію, встановивши рівень кількості полігонів. Якщо встановлено, target_polycount ігнорується.
Доступні значення:
- 1: Адаптивний — ультра кількість полігонів.
- 2: Адаптивний — висока кількість полігонів.
- 3: Адаптивний — середня кількість полігонів.
- 4: Адаптивний — низька кількість полігонів.
Name
save_pre_remeshed_model
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, Meshy також зберігає додатковий GLB-файл до завершення етапу ремешу.

Name
target_polycount
Type
integer
Description
Цільова кількість полігонів (граней) у результаті. Фактична кількість може відрізнятися від цільової залежно від геометрії.
target_polycount впливає на результат у двох незалежних випадках:
- Ремеш — з should_remesh: true для моделі standard. Сітка ремешиться (децимується) приблизно до цієї кількості. Діапазон від 100 до 300 000, за замовчуванням 30 000. Якщо встановлено decimation_mode, він має пріоритет, а target_polycount ігнорується.
- Smart Topology — з model_type: smart-topology та ai_model: meshy-t2. Модель генерується одразу з цією кількістю граней; ремеш не виконується, і should_remesh не потрібен. Діапазон від 100 до 15 000, за замовчуванням 4 000.

Name
symmetry_mode
Type
string
⚠ застарілий
за замовчуванням auto
Description
Застаріле. Цей параметр більше не впливає на результат.
Поле symmetry_mode керує поведінкою симетрії під час процесу генерації моделі.
Допустимі значення:
- off: Вимикає симетрію.
- auto: Автоматично визначає та застосовує симетрію на основі вхідної геометрії.
- on: Примусово застосовує симетрію під час генерації.
Name
pose_mode
Type
string
за замовчуванням ""
Description
Вкажіть режим пози для згенерованої моделі.
Доступні значення:
- a-pose: Генерувати модель у позі A.
- t-pose: Генерувати модель у позі T.
- "" (порожній рядок): Без застосування конкретної пози.
Name
is_a_t_pose
Type
boolean
⚠ застарілий
за замовчуванням false
Description
Натомість використовуйте pose_mode. Чи генерувати модель у позі A/T.
Name
surface_mode
Type
string
⚠ застарілий
Description
Більше не впливає на результат. Він вибирав метод генерації моделі, який відтоді виведено з використання; натомість використовуйте ai_model.
Допустимі значення: organic та hard; будь-яке інше значення повертає 400.
Name
image_enhancement
Type
boolean
за замовчуванням true
Description
Оптимізує вхідне зображення для отримання кращих результатів. Встановіть значення false, щоб зберегти точний вигляд вхідного зображення без будь-якої стилізації.
Підтримується лише коли ai_model має значення meshy-6, meshy-7.1 або latest. Встановлення цього параметра з meshy-6-lite або з model_type: smart-topology повертає помилку.
Name
remove_lighting
Type
boolean
за замовчуванням true
Description
Прибирає відблиски та тіні з текстури базового кольору, забезпечуючи чистіший результат, який краще працює за умов нестандартного освітлення.
Діє лише коли ai_model має значення meshy-6. meshy-7.1 та latest приймають цей параметр, але ігнорують його. Встановлення цього параметра з meshy-6-lite або з model_type: smart-topology повертає помилку.
Name
moderation
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, вхідний контент буде автоматично перевірено на потенційно шкідливий вміст. Якщо виявлено шкідливий контент, завдання не перейде до етапу генерації.
Перевірятиметься контент із вхідних параметрів image_url, texture_image_url та texture_prompt.
Name
target_formats
Type
string[]
Description
Вказує, які формати 3D-файлів слід включити в результат. Будуть згенеровані та повернуті лише запитані формати, що може скоротити час виконання завдання. Якщо параметр не вказано, включаються всі підтримувані формати.
Доступні значення: glb, obj, fbx, stl, usdz, 3mf
Якщо параметр не вказано, генеруються всі формати, крім 3mf. 3mf включається лише якщо вказано явно.
Name
auto_size
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, сервіс використовує AI-зір для автоматичної оцінки реальної висоти об'єкта та відповідно змінює розмір моделі. Початок координат за замовчуванням матиме значення bottom, якщо тільки явно не вказано origin_at.
Name
alpha_thumbnail
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, завдання додатково рендерить версію попереднього перегляду з прозорим фоном (RGBA) та повертає її як alpha_thumbnail_url у відповіді GET. Наявне поле thumbnail_url залишається без змін.
Name
multi_view_thumbnails
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, завдання додатково рендерить чотири мініатюри з основних ракурсів (спереду, справа, ззаду, зліва) та повертає їх у thumbnail_urls у відповіді GET. Наявне поле thumbnail_url залишається без змін і продовжує вказувати на вигляд спереду, тому це не впливає на наявних клієнтів.
Додає приблизно 3 секунди до затримки виконання завдання.

Застосовується лише коли auto_size = true

Name
origin_at
Type
string
за замовчуванням bottom
Description
Положення початку координат, коли увімкнено auto_size.
Доступні значення: bottom, center.

Результати

Властивість result відповіді містить id завдання щойно створеного завдання Зображення у 3D.

Режими помилок

Name
400 - Bad Request
Description
Запит був неприйнятним. Поширені причини:
- Відсутній параметр: Необхідно вказати або image_url, або input_task_id.
- Недійсне вхідне завдання: input_task_id має посилатися на завдання Текст у зображення або Зображення у зображення зі статусом SUCCEEDED, яке створює рівно одне зображення.
- Недійсний формат зображення: Наданий image_url має непідтримуваний формат (.jpg, .jpeg, .png, .webp).
- Недоступна URL-адреса: Не вдалося завантажити image_url (404 або timeout).
- Занадто велике зображення: Зображення image_url або texture_image_url перевищує 20 МБ.
- Недійсний Data URI: Рядок base64 має неправильний формат.
- Недійсна комбінація параметрів: enable_pbr підтримується лише коли should_texture має значення true.
- Непідтримувана модель для низькополігональної генерації: ai_model: "meshy-6-lite" не підтримує model_type: "lowpoly".
- Непідтримувана модель для Ultra: geometry_resolution потребує meshy-7.1 або latest.
- Непідтримувана модель для параметрів зображення: image_enhancement або remove_lighting встановлено разом з ai_model: "meshy-6-lite" або model_type: "smart-topology".
Name
401 - Unauthorized
Description
Помилка автентифікації. Перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти запитів.

Request

POST

/openapi/v1/image-to-3d

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

# With 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"]
  }'

Response

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

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

Отримати завдання «Зображення у 3D»

Ця кінцева точка дозволяє отримати завдання «Зображення у 3D» за дійсним id завдання. Див. Об'єкт завдання «Зображення у 3D», щоб дізнатися, які властивості входять до складу об'єкта завдання «Зображення у 3D».

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор завдання «Зображення у 3D», яке потрібно отримати.

Повертає

Відповідь містить об'єкт завдання «Зображення у 3D». Дивіться розділ Об'єкт завдання «Зображення у 3D» для деталей.

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": {
    "message": ""
  },
  "consumed_credits": 30
}

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

Видалити задачу Зображення у 3D

Ця кінцева точка остаточно видаляє задачу Зображення у 3D, включно з усіма пов'язаними моделями та даними. Ця дія незворотна.

Параметри шляху

Name
id
Type
path
Description
ID задачі Зображення у 3D, яку потрібно видалити.

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

Задача, яка ще перебуває у стані PENDING, видаляється, а кредити, витрачені під час створення, повертаються.

Задачу, яка вже перебуває у стані IN_PROGRESS, видалити не можна: запит відхиляється з кодом 409 Conflict, а задача продовжує виконуватися. Кредити за задачу, яку воркер уже почав виконувати, не підлягають поверненню, тому видалення її під час виконання коштувало б вам і кредитів, і результату. Дочекайтеся, поки вона перейде у стан SUCCEEDED, FAILED або CANCELED, а потім видаліть її.

Задача у кінцевому стані (SUCCEEDED, FAILED або CANCELED) видаляється без повернення коштів.

Повертає

Повертає 200 OK у разі успіху або 409 Conflict, якщо задача перебуває у стані IN_PROGRESS.

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 is left 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."
}

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

List Image to 3D Tasks

Ця кінцева точка дозволяє отримати список завдань Зображення у 3D.

Параметри

Необов'язкові атрибути

Name
page_num
Type
integer
Description
Номер сторінки для пагінації. Починається та за замовчуванням дорівнює 1.
Name
page_size
Type
integer
Description
Обмеження розміру сторінки. За замовчуванням 10 елементів. Максимально дозволено 100 елементів.
Name
sort_by
Type
string
Description
Поле для сортування. Доступні значення:
- +created_at: Сортувати за часом створення у порядку зростання.
- -created_at: Сортувати за часом створення у порядку спадання.

Повертає

Повертає розбитий на сторінки список об'єктів завдання Зображення у 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": {
      "message": ""
    },
    "consumed_credits": 30
  }
]

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

Потокова передача завдання Зображення у 3D

Ця кінцева точка передає оновлення в реальному часі для завдання Зображення у 3D за допомогою Server-Sent Events (SSE).

Параметри

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

Повертає

Повертає потік об'єктів завдання Зображення у 3D у форматі Server-Sent Events.

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

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

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

The Image to 3D Task Object

Об'єкт задачі Зображення у 3D — це одиниця роботи, яку Meshy відстежує для генерації 3D-моделі з вхідного зображення. Об'єкт має такі властивості:

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор задачі. Хоча ми використовуємо k-сортований UUID для ідентифікаторів задач як деталь реалізації, вам не слід робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип задачі Зображення у 3D. Значення — image-to-3d.
Name
model_urls
Type
object
Description
Посилання для завантаження текстурованого файлу 3D-моделі, згенерованого Meshy. Властивість для певного формату буде відсутня, якщо цей формат не було згенеровано, замість повернення порожнього рядка.
- 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. Присутнє лише тоді, коли 3mf було запитано через target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Посилання для завантаження оригінального вихідного файлу GLB до remesh.
  Доступне лише тоді, коли задачу було створено з обома параметрами should_remesh: true та save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
Посилання для завантаження зображення-мініатюри файлу моделі. Еквівалентне thumbnail_urls.front, коли воно присутнє, збережено для зворотної сумісності.
Name
alpha_thumbnail_url
Type
string
Description
Посилання для завантаження версії thumbnail_url з прозорим фоном (RGBA). Присутнє лише тоді, коли задачу було створено з параметром alpha_thumbnail: true і прозорий попередній перегляд було успішно відрендерено; інакше це поле відсутнє.
Name
thumbnail_urls
Type
object
Description
Посилання для завантаження чотирьох мініатюр згенерованої 3D-моделі з основних ракурсів. Кожне значення — це підписане посилання на PNG-зображення розміром 512×512, відрендерене з тими самими матеріалами та освітленням, що й thumbnail_url. Корисно для попереднього перегляду моделі з кількох кутів у пакетних конвеєрах без завантаження GLB.
Присутнє лише тоді, коли задачу було створено з параметром multi_view_thumbnails: true і вона досягла статусу SUCCEEDED. Старіші задачі та задачі, створені без цього явного вмикання, не включатимуть це поле.
- Name
  front
  Type
  string
  Description
  Вигляд спереду, поворот на 0° навколо вертикальної осі (відповідає thumbnail_url).
- Name
  right
  Type
  string
  Description
  Вигляд справа, поворот на 90°.
- Name
  back
  Type
  string
  Description
  Вигляд ззаду, поворот на 180°.
- Name
  left
  Type
  string
  Description
  Вигляд зліва, поворот на 270°.
Name
texture_prompt
Type
string
Description
Текстовий prompt, що використовувався для керування процесом текстурування.
Name
texture_image_url
Type
string
Description
Посилання для завантаження зображення текстури, яке використовувалося для керування процесом текстурування.
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
Мітка часу початку виконання задачі, у мілісекундах. Якщо задача ще не розпочата, ця властивість матиме значення 0.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року UTC, відповідно до стандарту RFC 3339. Наприклад, п'ятниця, 1 вересня 2023 року, 12:00:00 за GMT представлена як 1693569600000. Це стосується всіх міток часу в Meshy API.
Name
created_at
Type
timestamp
Description
Мітка часу створення задачі, у мілісекундах.
Name
expires_at
Type
timestamp
Description
Мітка часу завершення терміну дії результату задачі, у мілісекундах.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення задачі, у мілісекундах. Якщо задача ще не завершена, ця властивість матиме значення 0.
Name
status
Type
string
Description
Статус задачі. Можливі значення: одне з PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Масив об'єктів посилань на текстури, згенеровані задачею. Зазвичай тут міститься лише один об'єкт посилання на текстуру. Кожне посилання на текстуру має такі властивості:
- 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
  Посилання для завантаження зображення карти випромінювання.
  Якщо задачу створено з параметром enable_pbr: false, або ai_model має значення meshy-6-lite, meshy-7.1, meshy-t2 чи latest, ця властивість буде відсутня.
Name
preceding_tasks
Type
integer
Description
Кількість попередніх задач.
Значення цього поля має сенс лише якщо статус задачі — PENDING.
Name
task_error
Type
object
Description
Деталі помилки для невдалих задач. Див. Помилки для повного опису об'єкта task_error.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, витрачених на цю задачу. Присутнє, коли статус задачі — PENDING, IN_PROGRESS або SUCCEEDED. Повертає 0 для задач зі статусом FAILED (кредити повертаються у разі невдачі).

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": {
    "message": ""
  },
  "consumed_credits": 30
}