Текст у 3D API

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

Текст у 3D використовує дворівневий робочий процес. Спочатку створіть завдання preview (mode: "preview"), щоб згенерувати 3D-сітку без текстури, аби ви могли оцінити форму. Потім передайте ID завершеного завдання preview у завдання refine (mode: "refine"), щоб застосувати текстуру до сітки. Обидва кроки використовують одну й ту саму кінцеву точку.

POST/openapi/v2/text-to-3d

Create a Text to 3D Preview Task

Ця кінцева точка створює попередню (preview) задачу Текст у 3D, яка генерує сітку без текстур (тільки геометрію) на основі текстового prompt. Це перший крок дворівневого робочого процесу. Після успішного завершення preview використайте отриманий ID задачі, щоб створити refine-задачу для текстурування. Див. Об'єкт задачі Текст у 3D для повної схеми відповіді.

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

Параметри

Name
mode
Type
string
Обов'язковий
Description
Це поле має бути встановлено значення "preview" при створенні попередньої задачі.
Name
prompt
Type
string
Обов'язковий
Description
Опишіть, якого типу об'єкт представляє 3D-модель. Максимум 800 символів.
Name
model_type
Type
string
за замовчуванням standard
Description
Вкажіть тип генерації 3D-сітки.
Доступні значення:
- standard: звичайна генерація 3D-сітки з високою деталізацією.
- smart-topology: оберіть модель Smart Topology за допомогою ai_model (meshy-t2 або meshy-t2.5).
- lowpoly (застаріле, буде вилучено 30 жовтня 2026 року): генерує низькополігональну сітку, оптимізовану для чистіших полігонів. Натомість рекомендуємо Meshy T2.5: smart-topology з meshy-t2.5.
Коли обрано smart-topology, параметри should_remesh і decimation_mode ігноруються, і приймається лише topology: triangle.
lowpoly буде вилучено 30 жовтня 2026 року. Після цієї дати запити з model_type: "lowpoly" повертатимуть помилку. Рекомендуємо перейти на Meshy T2.5 (model_type: "smart-topology" з ai_model: "meshy-t2.5"). Коли обрано lowpoly, параметри ai_model, topology, target_polycount і should_remesh ігноруються.
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.
- meshy-t2.5 (за замовчуванням): чіткіша деталізація для ігрових asset-ів. Вихід у вигляді трикутників, кількість граней можна задати через target_polycount.
Name
geometry_resolution
Type
string
за замовчуванням standard
Description
Прохід генерації геометрії. 2k запускає прохід Ultra з роздільністю 2048³; 4k запускає його з роздільністю 4096³ для найтоншої деталізації поверхні.
Доступні значення: standard, 2k, 4k
Підтримується лише в режимі preview. Потребує meshy-7.1 або latest.
Name
ultra_mode
Type
boolean
⚠ застарілий
за замовчуванням false
Description
Використовуйте натомість geometry_resolution. ultra_mode: true еквівалентне geometry_resolution: "2k".
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 або meshy-t2.5 повертає помилку.
Name
decimation_mode
Type
integer
Description
Увімкнути адаптивну децимацію, задавши рівень кількості полігонів. Якщо встановлено, target_polycount ігнорується.
Доступні значення:
- 1: адаптивний — ультра кількість полігонів.
- 2: адаптивний — висока кількість полігонів.
- 3: адаптивний — середня кількість полігонів.
- 4: адаптивний — низька кількість полігонів.

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 або meshy-t2.5. Модель генерується одразу з цією кількістю граней; ремеш не виконується, і should_remesh не потрібен. Для meshy-t2: діапазон від 100 до 15 000, за замовчуванням 4 000. Для meshy-t2.5: діапазон від 100 до 30 000, за замовчуванням 15 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
art_style
Type
string
⚠ застарілий
за замовчуванням realistic
Description
Не підтримується Meshy-6. Запити з використанням Meshy-6 ігноруватимуть art_style, і деякі комбінації можуть спричиняти помилки. Доступні значення: realistic, sculpture.
enable_pbr слід встановити у значення false при використанні стилю Sculpture, оскільки стиль Sculpture генерує власний набір PBR-карт.
Name
moderation
Type
boolean
за замовчуванням false
Description
Якщо встановлено true, вхідний контент буде автоматично перевірено на потенційно шкідливий вміст. Якщо виявлено шкідливий вміст, задача не перейде до генерації.
Текст із prompt буде перевірено.
Name
target_formats
Type
string[]
Description
Вказує, які формати 3D-файлів включати у результат. Генеруватимуться та повертатимуться лише запитані формати, що може скоротити час виконання задачі. Якщо не вказано, включаються всі підтримувані формати.
Доступні значення: glb, obj, fbx, stl, usdz, 3mf
Якщо не вказано, генеруються всі формати, крім 3mf. 3mf включається лише якщо вказано явно.
Name
alpha_thumbnail
Type
boolean
за замовчуванням false
Description
Якщо встановлено true, задача додатково рендерить версію preview з прозорим фоном (RGBA) та повертає її як alpha_thumbnail_url у відповіді GET. Наявне поле thumbnail_url залишається без змін.
Name
auto_size
Type
boolean
за замовчуванням false
Description
Якщо встановлено true, сервіс використовує AI vision для автоматичної оцінки реальної висоти об'єкта та відповідного зміни розміру моделі. Початок координат за замовчуванням буде bottom, якщо origin_at не встановлено явно.

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

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

Результати

Властивість result у відповіді містить id задачі щойно створеної задачі Текст у 3D.

Режими збою

Name
400 - Bad Request
Description
Запит неприйнятний. Поширені причини:
- Відсутній параметр: не вказано обов'язковий параметр (наприклад, prompt, mode).
- Недійсний параметр: art_style не є одним із дозволених значень.
- Занадто довгий prompt: prompt перевищує обмеження на кількість символів.
- Непідтримувана модель для low poly: ai_model: "meshy-6-lite" не підтримує model_type: "lowpoly".
- Непідтримувана модель для Ultra: geometry_resolution потребує meshy-7.1 або latest.
Name
401 - Unauthorized
Description
Помилка автентифікації. Будь ласка, перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цієї задачі.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти запитів.

Request

POST

/openapi/v2/text-to-3d

# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

POST/openapi/v2/text-to-3d

Create a Text to 3D Refine Task

Ця кінцева точка створює завдання refine для Text to 3D, яке застосовує текстуру до завершеної попередньо переглянутої сітки (preview). Вам потрібно надати preview_task_id з успішного завдання попереднього перегляду. Це другий крок дворівневого робочого процесу.

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

Параметри

Name
mode
Type
string
Обов'язковий
Description
Це поле має бути встановлене на "refine" при створенні завдання refine.
Name
preview_task_id
Type
string
Обов'язковий
Description
Ідентифікатор відповідного завдання попереднього перегляду.
Статус вказаного завдання попереднього перегляду повинен бути SUCCEEDED.
Name
enable_pbr
Type
boolean
за замовчуванням false
Description
Генерувати PBR-карти (металевість, шорсткість, нормалі) на додаток до базового кольору. Карта випромінювання (emission) також включається, коли ai_model має значення meshy-6, за винятком texture_resolution: 8k (карта випромінювання не створюється). meshy-6-lite, meshy-7.1 та latest не створюють карту випромінювання, так само як і refine попереднього перегляду meshy-t2, у якому не вказано ai_model.
Name
texture_resolution
Type
string
за замовчуванням 2k
Description
Роздільна здатність текстури базового кольору. Одне зі значень: 2k (2048×2048), 4k (4096×4096) або 8k (8192×8192). Вища роздільна здатність дозволяє отримати більше деталей поверхні. Застосовується лише в режимі refine.
4k і 8k вимагають ai_model зі значенням meshy-6, meshy-7.1 або latest. При 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.
Name
ai_model
Type
string
за замовчуванням inherited from the preview task
Description
Ідентифікатор моделі, яку використовувати для refine.
Доступні значення:
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (застаріле): замість цього використовуйте meshy-7.1.
Пропустіть цей параметр, щоб успадкувати модель, яку використовувало завдання попереднього перегляду, — це дозволяє зберегти однакову модель для попереднього перегляду та його refine від початку до кінця. Передайте явне значення, щоб перевизначити це успадкування.
Явне значення latest розв'язується тут так само, як і в завданні попереднього перегляду (наразі Meshy 7.1), тому попередній перегляд із latest і його refine з latest завжди використовують одну й ту саму модель текстурування.
Name
moderation
Type
boolean
за замовчуванням false
Description
Якщо встановлено true, вхідний контент автоматично перевірятиметься на потенційно шкідливий вміст. Якщо виявлено шкідливий контент, завдання не перейде до етапу генерації.
Перевірятиметься як текст з texture_prompt, так і зображення з texture_image_url.
Name
remove_lighting
Type
boolean
за замовчуванням true
Description
Видаляє відблиски та тіні з текстури базового кольору, забезпечуючи чистіший результат, який краще працює за умов власного налаштування освітлення.
Застосовується лише тоді, коли ai_model має значення meshy-6. meshy-7.1 та latest приймають цей параметр, але ігнорують його — так само, як і refine попереднього перегляду meshy-t2, у якому не вказано ai_model. Встановлення цього параметра з meshy-6-lite призводить до помилки.
Name
target_formats
Type
string[]
Description
Визначає, які формати 3D-файлів включити до результату. Будуть згенеровані та повернуті лише запитані формати, що може скоротити час виконання завдання. Якщо не вказано, включаються всі підтримувані формати.
Доступні значення: glb, obj, fbx, stl, usdz, 3mf
Якщо параметр не вказано, генеруються всі формати, крім 3mf. 3mf включається лише тоді, коли вказано явно.
Name
alpha_thumbnail
Type
boolean
за замовчуванням false
Description
Якщо встановлено true, завдання додатково рендерить версію попереднього перегляду з прозорим фоном (RGBA) і повертає її як alpha_thumbnail_url у відповіді GET. Наявне поле thumbnail_url залишається без змін.
Name
auto_size
Type
boolean
за замовчуванням false
Description
Якщо встановлено true, сервіс використовує AI-зір, щоб автоматично оцінити реальну висоту об'єкта та відповідно змінити розмір моделі. Початок координат за замовчуванням буде bottom, якщо явно не вказано origin_at.

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

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

Повертає

Властивість result відповіді містить id завдання новоствореного завдання Text to 3D.

Режими відмов

Name
400 - Bad Request
Description
Запит був неприйнятним. Поширені причини:
- Недійсний ідентифікатор завдання: preview_task_id недійсний або не існує.
- Завдання не готове: завдання попереднього перегляду ще не завершилося успішно.
- Невідповідність моделей: AI-модель завдання попереднього перегляду несумісна із запитуваною моделлю refine.
- Непідтримувана модель для remove_lighting: remove_lighting встановлено разом з ai_model: "meshy-6-lite".
Name
401 - Unauthorized
Description
Помилка автентифікації. Перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
404 - Not Found
Description
Завдання попереднього перегляду, вказане через preview_task_id, не знайдено.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти.

Request

POST

/openapi/v2/text-to-3d

# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

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

GET/openapi/v2/text-to-3d/:id

Отримати завдання Text to 3D

Ця кінцева точка дозволяє отримати завдання Текст у 3D за дійсним id завдання. Зверніться до розділу Об'єкт завдання Text to 3D, щоб побачити, які властивості включені в об'єкт завдання Text to 3D.

Ця кінцева точка працює як для завдань preview, так і для завдань refine.

Параметри

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

Повертає

Відповідь містить об'єкт завдання Text to 3D. Деталі дивіться в розділі Об'єкт завдання Text to 3D.

Приклади

Режим	Приклад моделі
Preview
Refine

Request

GET

/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}

DELETE/openapi/v2/text-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/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-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/v2/text-to-3d

List Text to 3D Tasks

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

Параметри

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

Повертає

Повертає список з пагінацією об'єктів завдання Текст у 3D.

Request

GET

/openapi/v2/text-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

GET/openapi/v2/text-to-3d/:id/stream

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

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

Параметри

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

Повертає

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

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

Request

GET

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

curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": 20
}

Об'єкт завдання Text to 3D

Об'єкт завдання Text to 3D — це робоча одиниця, яку Meshy відстежує для генерації 3D-моделі з текстового вводу. Існує два етапи API Text to 3D: preview і refine. Етап preview призначений для генерації 3D-моделі лише з сіткою, а етап refine — для генерації текстурованої 3D-моделі на основі результату етапу preview.

Об'єкт має такі властивості:

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор завдання. Хоча в якості деталі реалізації ми використовуємо k-сортований UUID для ідентифікаторів завдань, вам не слід робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання Text to 3D. Можливі значення: text-to-3d-preview для завдань етапу preview та text-to-3d-refine для завдань етапу refine.
Name
model_urls
Type
object
Description
Посилання для завантаження текстурованого файлу 3D-моделі, згенерованого Meshy. Властивість для формату буде пропущена, якщо формат не згенеровано, замість повернення порожнього рядка.
- Name
  glb
  Type
  string
  Description
  Посилання для завантаження файлу GLB.
- Name
  fbx
  Type
  string
  Description
  Посилання для завантаження файлу FBX.
- Name
  usdz
  Type
  string
  Description
  Посилання для завантаження файлу USDZ.
- Name
  obj
  Type
  string
  Description
  Посилання для завантаження файлу OBJ.
- Name
  mtl
  Type
  string
  Description
  Посилання для завантаження файлу MTL.
- Name
  stl
  Type
  string
  Description
  Посилання для завантаження файлу STL.
- Name
  3mf
  Type
  string
  Description
  Посилання для завантаження файлу 3MF. Присутнє лише тоді, коли 3mf було запитано через target_formats.
Name
prompt
Type
string
Description
Це незмінений prompt, який було використано для створення завдання.
Name
negative_prompt
Type
string
⚠ застарілий
Description
Збережено для зворотної сумісності. Це поле не впливає на згенеровані моделі.
Name
art_style
Type
string
⚠ застарілий
Description
Незмінений art_style, який було використано для створення завдання preview. Не підтримується Meshy-6.
Name
texture_richness
Type
string
⚠ застарілий
Description
Збережено для зворотної сумісності. Це поле не впливає на згенеровані моделі.
Name
texture_prompt
Type
string
Description
Додатковий текстовий prompt, наданий для керування процесом текстурування на етапі refine.
Name
ultra_mode
Type
boolean
⚠ застарілий
Description
Застаріле; натомість використовуйте geometry_resolution.
Name
geometry_resolution
Type
string
Description
Рівень Ultra, з яким виконувалося завдання preview (2k або 4k); пропускається для standard.
Name
texture_image_url
Type
string
Description
Посилання для завантаження зображення текстури, яке використовувалося для керування процесом текстурування.
Name
thumbnail_url
Type
string
Description
Посилання для завантаження мініатюри файлу моделі.
Name
alpha_thumbnail_url
Type
string
Description
Посилання для завантаження версії thumbnail_url з прозорим фоном (RGBA). Присутнє лише тоді, коли завдання було створено з alpha_thumbnail: true і прозорий попередній перегляд було успішно відрендерено; інакше це поле пропускається.
Name
video_url
Type
string
⚠ застарілий
Description
Посилання для завантаження попереднього відео. Буде видалено в майбутньому релізі.
Name
progress
Type
integer
Description
Прогрес виконання завдання. Якщо завдання ще не розпочато, ця властивість дорівнюватиме 0. Щойно завдання завершиться успішно, вона стане 100.
Name
started_at
Type
timestamp
Description
Мітка часу початку виконання завдання, у мілісекундах. Якщо завдання ще не розпочато, ця властивість дорівнюватиме 0.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року UTC, відповідно до стандарту RFC 3339. Наприклад, п'ятниця, 1 вересня 2023 року, 12:00:00 за Гринвічем представлена як 1693569600000. Це стосується всіх міток часу в Meshy API.
Name
created_at
Type
timestamp
Description
Мітка часу створення завдання, у мілісекундах.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення завдання, у мілісекундах. Якщо завдання ще не завершено, ця властивість дорівнюватиме 0.
Name
status
Type
string
Description
Статус завдання. Можливі значення: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Масив об'єктів URL текстур, згенерованих завданням. Зазвичай тут міститься лише один об'єкт URL текстури. Кожен URL текстури має такі властивості:
- Name
  base_color
  Type
  string
  Description
  Посилання для завантаження зображення карти базового кольору.
- 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 або latest, або якщо завдання виконує refine для preview meshy-t2 без встановлення ai_model, ця властивість буде пропущена.
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 Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}