Текст у 3D API
Генеруйте 3D-моделі з текстових запитів у власному додатку.
Текст у 3D працює у два етапи. Спочатку створіть задачу preview (mode: "preview"), щоб згенерувати 3D-сітку без текстури, аби ви могли перевірити форму. Потім надішліть ID успішної задачі preview до задачі refine (mode: "refine"), щоб накласти текстуру на сітку. Обидва етапи використовують ту саму кінцеву точку.
Створення задачі попереднього перегляду Текст у 3D
Створює задачу попереднього перегляду Текст у 3D, яка генерує нетекстуровану 3D сітку (лише геометрію) з текстового prompt. Це перший крок дворівневого робочого процесу. Після успішного завершення попереднього перегляду надішліть його ID задачі у refine-задачі, щоб текстурувати сітку. Див. Створення задачі Текст у 3D refine. Повну схему відповіді див. у розділі Об'єкт задачі Текст у 3D.
Задача виконується у фоновому режимі. Про типову тривалість виконання задачі див. у розділі Час обробки.
Request
# 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"
}
Параметри
- Name
- mode
- Type
- string
- Обов'язковий
- Description
Етап дворівневого робочого процесу. Надішліть
preview, щоб створити задачу попереднього перегляду.
- Name
- prompt
- Type
- string
- Обов'язковий
- Description
Текст, що описує об'єкт для генерації, до 800 символів. Довший текст повертає
400.
- Name
- model_type
- Type
- string
- за замовчуванням standard
- Description
Тип 3D сітки для генерації.
Доступні значення:
standard: високодеталізована 3D сіткаsmart-topology: сітка Smart Topology. Виберіть модель за допомогоюai_model(meshy-t2абоmeshy-t2.5).
З
smart-topologyMeshy ігноруєshould_remeshіdecimation_mode, та приймає лишеtopology: triangle.
- Name
- ai_model
- Type
- string
- за замовчуванням latest
- Description
AI-модель, що генерує 3D модель. Доступні значення залежать від
model_type.Стандартні моделі (
model_type: standard):meshy-6-litemeshy-6meshy-7.1latest: Meshy 7.1meshy-7(застаріле): надсилайте натомістьmeshy-7.1
Моделі Smart Topology (
model_type: smart-topology):meshy-t2: чистіший topology, нативно розділені частини, вихід у трикутниках, і кількість граней, яку ви задаєте черезtarget_polycountmeshy-t2.5(за замовчуванням): чіткіша деталізація для ігрових asset, вихід у трикутниках, і кількість граней, яку ви задаєте черезtarget_polycount
Див. Моделі, яка модель підходить для вашого проєкту, наприклад персонажа гри чи моделі для 3D-друку.
- Name
- geometry_resolution
- Type
- string
- за замовчуванням standard
- Description
Прохід генерації геометрії. Застосовується лише до задач попереднього перегляду. Refine з цим параметром повертає
400.Доступні значення:
standard2k: запускає прохід Ultra з роздільною здатністю 2048³4k: запускає прохід Ultra з роздільною здатністю 4096³, для детальнішої проробки поверхні
2kпотребуєmeshy-7.1,latestабо застарілоїmeshy-7.4kпотребуєmeshy-7.1абоlatest. Інші моделі повертають400.
- Name
- ultra_mode
- Type
- boolean
- ⚠ застарілий
- за замовчуванням false
- Description
Надсилайте натомість
geometry_resolution.ultra_mode: trueеквівалентноgeometry_resolution: "2k".
- 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зai_modelmeshy-t2абоmeshy-t2.5повертає400.
- Name
- decimation_mode
- Type
- integer
- Description
Адаптивна кількість граней, за рівнем. Коли ви її задаєте, Meshy ігнорує
target_polycount.Доступні значення:
1: ультра2: висока3: середня4: низька
- Name
- target_polycount
- Type
- integer
- Description
Цільова кількість граней. Результат може відрізнятися від цілі залежно від геометрії. Застосовується у двох окремих випадках:
- Ремеш: з
should_remesh: trueдляstandard-моделі. Meshy ремешує (децимує) сітку приблизно до цієї кількості. Якщо ви задалиdecimation_mode, Meshy використовує його та ігноруєtarget_polycount. - Smart Topology: з
model_type: smart-topologyтаai_modelmeshy-t2абоmeshy-t2.5. Meshy генерує модель з такою кількістю граней безпосередньо. Ремеш не виконується, іshould_remeshне потрібен.
У таблиці нижче показано діапазон і значення за замовчуванням для кожного випадку:
Випадок Діапазон За замовчуванням Ремеш 100до30000030000meshy-t2100до150004000meshy-t2.5100до3000015000Значення поза діапазоном повертає
400.Для низькополігонального ігрового asset використовуйте модель Smart Topology замість ремешу стандартної моделі. Див. Моделі.
- Ремеш: з
- Name
- symmetry_mode
- Type
- string
- ⚠ застарілий
- за замовчуванням auto
- Description
Не вказуйте. Цей параметр не впливає на результат.
Доступні значення:
off: вимикає симетріюauto: застосовує симетрію на основі вхідної геометріїon: примусово застосовує симетрію під час генерації
- Name
- pose_mode
- Type
- string
- Description
Поза для моделі персонажа,
a-poseабоt-pose. Щоб не застосовувати позу, не вказуйтеpose_modeіis_a_t_pose.
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ застарілий
- за замовчуванням false
- Description
Надсилайте натомість
pose_mode. Чи генерувати модель у позі A чи у позі T.
- Name
- art_style
- Type
- string
- ⚠ застарілий
- за замовчуванням realistic
- Description
Не вказуйте. Meshy ігнорує цей параметр.
- Name
- moderation
- Type
- boolean
- за замовчуванням false
- Description
Чи перевіряти
promptна шкідливий вміст перед генерацією. Якщо Meshy виявляє шкідливий вміст, запит повертає400, і Meshy не створює задачу.
- Name
- target_formats
- Type
- string[]
- Description
Формати файлів для генерації. Meshy генерує та повертає лише ці формати, що може скоротити час виконання задачі. Якщо ви не вкажете цей параметр, Meshy генерує всі формати, крім
3mf, який генерується лише за запитом.Доступні значення:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- за замовчуванням false
- Description
Чи також рендерити попередній перегляд з прозорим фоном (RGBA), що повертається у
alpha_thumbnail_urlпри отриманні задачі.thumbnail_urlне змінюється.
- Name
- auto_size
- Type
- boolean
- за замовчуванням false
- Description
Чи оцінювати реальну висоту об'єкта за допомогою AI-зору та змінювати розмір моделі відповідно до неї. Meshy розміщує початок координат знизу, якщо ви не задали
origin_at.
auto_size = true- Name
- origin_at
- Type
- string
- за замовчуванням bottom
- Description
Де розмістити початок координат моделі,
bottomабоcenter.
Повертає
Поле result відповіді містить ID нової задачі Текст у 3D.
Режими відмови
- Name
400 - Bad Request- Description
Запит не може бути виконаний. Повідомлення про помилку вказує, яку проблему виявлено. Наприклад:
- Відсутній параметр: обов'язковий параметр, наприклад
promptабоmode, відсутній. - Prompt занадто довгий:
promptперевищує ліміт символів. - Непідтримувана модель для Ultra:
geometry_resolution—2kабо4k, зai_model, яка не підтримує цей режим.
Виправте запит і надішліть його знову. Див. Помилки.
- Відсутній параметр: обов'язковий параметр, наприклад
- Name
401 - Unauthorized- Description
API-ключ відсутній або недійсний. Перевірте заголовок
Authorization.
- Name
402 - Payment Required- Description
Наприклад:
- Недостатньо кредитів: на обліковому записі недостатньо кредитів для цієї задачі, або обліковий запис досяг ліміту кредитів. Перевірте свій баланс кредитів, потім повторіть спробу.
- Безкоштовний план: для створення задачі потрібен платний план. Оновіть свій план у налаштуваннях підписки, потім повторіть спробу.
- Name
403 - Forbidden- Description
Модерація вмісту заблокувала prompt або вхідне зображення. Змініть вхідні дані, потім повторіть спробу.
- Name
429 - Too Many Requests- Description
Ви перевищили обмеження частоти запитів. Зачекайте, потім повторіть спробу. Див. Обмеження частоти.
Create a Text to 3D refine task
Створює завдання Refine для Текст у 3D, яке текстурує сітку завершеного preview-завдання. Надішліть ID успішного preview-завдання як preview_task_id. Див. Створення preview-завдання Текст у 3D. Це другий крок двоетапного робочого процесу.
Завдання виконується у фоновому режимі. Про типову тривалість виконання завдання див. Час обробки.
Request
# 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
}'
# Refine with Meshy N1 from the preview's stored reference image
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",
"ai_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Параметри
- Name
- mode
- Type
- string
- Обов'язковий
- Description
Крок двоетапного робочого процесу. Надішліть
refine, щоб створити завдання refine.
- Name
- preview_task_id
- Type
- string
- Обов'язковий
- Description
ID preview-завдання, яке потрібно текстурувати. Preview-завдання повинно мати статус
SUCCEEDED.
- Name
- enable_pbr
- Type
- boolean
- за замовчуванням false
- Description
Чи потрібно також генерувати PBR-карти (metallic, roughness і normal) разом з базовим кольором.
З
ai_modelmeshy-6Meshy також генерує emission-карту, за виняткомtexture_resolution: 8k.meshy-6-lite,meshy-7,meshy-7.1таlatestне генерують emission-карту. Так само її не генерує refine preview-завданняmeshy-t2абоmeshy-t2.5, у якому не вказаноai_model. Зai_model: meshy-n1значенняtrueповертає400.
- Name
- texture_resolution
- Type
- string
- за замовчуванням 2k
- Description
Роздільна здатність текстури базового кольору. Застосовується лише до завдань refine. Надсилання цього параметра для preview повертає
400.Доступні значення:
2k: 2048×20484k: 4096×40968k: 8192×8192
Вища роздільна здатність дозволяє відтворити більше деталей поверхні.
4kі8kпотребуютьai_modelmeshy-6,meshy-7.1абоlatest. Зmeshy-n1вони повертають400. При8kMeshy не генерує emission-карту.
- 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_promptабоtexture_image_url, не обидва одразу. Якщо надіслати обидва, Meshy використовуєtexture_prompt. Зai_model: meshy-n1надсилання цього параметра повертає400.
- Name
- texture_image_url
- Type
- string
- Description
2D-зображення, що спрямовує текстурування, у вигляді публічного URL або закодованого у base64 data URI, наприклад
data:image/jpeg;base64,<ваші закодовані в base64 дані зображення>.Зображення має бути файлом
.jpg,.jpeg,.pngабо.webpрозміром не більше 20 МБ, не менше 32 пікселів з кожної сторони та не більше 178 956 970 пікселів (ширина × висота).З
ai_model: meshy-n1Meshy текстурує, використовуючи це зображення як вигляд спереду.Текстурування за зображенням може працювати некоректно, якщо форма на зображенні значно відрізняється від моделі.
- Name
- ai_model
- Type
- string
- за замовчуванням inherited from the preview task
- Description
AI-модель, яка текстурує сітку.
Доступні значення:
meshy-6-litemeshy-6meshy-7.1latest: Meshy 7.1meshy-n1: 2K-текстура базового кольору лише за референсним зображенням. Без текстового prompt, без PBR-карт, без 4K чи 8K.meshy-7(застаріле): замість цього надсилайтеmeshy-7.1
Залиште порожнім, щоб використати модель preview-завдання, тоді preview і його refine виконуються на тій самій моделі від початку до кінця. Надішліть значення, щоб перевизначити її. Явне значення
latestрозв'язується так само, як і для preview-завдання, тожlatestpreview і йогоlatestrefine завжди використовують ту саму модель текстурування.З
meshy-n1Meshy текстурує заtexture_image_url. Якщо його не надіслано, Meshy використовує референсне зображення, яке зберігає previewmeshy-7.1абоlatest. Будь-яке інше preview-завдання повертає400, якщо не надісланоtexture_image_url. Preview може мати щонайбільше 7 999 999 трикутників. Preview, у якого виконано remesh у quad-сітку, повертає400.
- Name
- moderation
- Type
- boolean
- за замовчуванням false
- Description
Чи потрібно перевіряти
texture_promptіtexture_image_urlна наявність шкідливого контенту перед генерацією. Якщо Meshy виявляє шкідливий контент, запит повертає400, і Meshy не створює завдання.
- Name
- remove_lighting
- Type
- boolean
- за замовчуванням true
- Description
Чи потрібно видаляти відблиски та тіні з текстури базового кольору. Чистіший результат краще працює за умов власного освітлення.
Діє лише коли
ai_model—meshy-6.meshy-7.1іlatestприймають цей параметр, але ігнорують його, так само як і refine preview-завданняmeshy-t2абоmeshy-t2.5, у якому не вказаноai_model. Надсилання цього параметра зmeshy-6-liteповертає400. Зmeshy-n1значенняtrueповертає400.
- Name
- target_formats
- Type
- string[]
- Description
Формати файлів, які потрібно згенерувати. Meshy генерує та повертає лише ці формати, що може скоротити час виконання завдання. Якщо параметр не вказано, Meshy генерує всі формати, крім
3mf, який генерується лише за окремим запитом.Доступні значення:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- за замовчуванням false
- Description
Чи потрібно також відрендерити preview з прозорим фоном (RGBA), яке повертається у
alpha_thumbnail_urlпід час отримання завдання.thumbnail_urlпри цьому не змінюється.
- Name
- auto_size
- Type
- boolean
- за замовчуванням false
- Description
Чи потрібно оцінити реальну висоту об'єкта за допомогою AI-зору та змінити розмір моделі відповідно до неї. Meshy розміщує початок координат знизу, якщо не задано
origin_at.
auto_size = true- Name
- origin_at
- Type
- string
- за замовчуванням bottom
- Description
Де розмістити початок координат моделі:
bottomабоcenter.
Результати
Поле result у відповіді містить ID нового завдання Текст у 3D.
Режими збою
- Name
400 - Bad Request- Description
Запит не може бути виконаний. У повідомленні про помилку вказано, яку саме проблему знайдено. Наприклад:
- Недійсний ID завдання:
preview_task_idнедійсний або не відповідає жодному з ваших preview-завдань. - Завдання не готове: Preview-завдання ще не завершилося успішно.
- Невідповідність моделей: AI-модель preview-завдання не сумісна із запитаною моделлю refine.
- Непідтримувана модель для remove_lighting:
remove_lightingбуло надіслано зai_model: "meshy-6-lite". - Немає референсного зображення для Meshy N1:
ai_model: meshy-n1надіслано безtexture_image_url, а preview не має референсного зображення, яке може використати Meshy N1. Надішлітьtexture_image_url. - Quad-preview для Meshy N1:
ai_model: meshy-n1надіслано для preview, у якого виконано remesh у quad-сітку. Виконайте refine з іншоюai_model. - Забагато трикутників для Meshy N1: З
ai_model: meshy-n1preview має більше ніж 7 999 999 трикутників. Виконайте refine з іншоюai_model. - Непідтримувана опція для Meshy N1:
ai_model: meshy-n1надіслано з однією з таких опцій:texture_promptenable_pbr: truetexture_resolutionзначенням4kабо8khd_texture: trueбезtexture_resolutionremove_lighting: true
Виправте запит і надішліть його знову. Див. Помилки.
- Недійсний ID завдання:
- Name
401 - Unauthorized- Description
API-ключ відсутній або недійсний. Перевірте заголовок
Authorization.
- Name
402 - Payment Required- Description
Наприклад:
- Недостатньо кредитів: На рахунку недостатньо кредитів для цього завдання, або рахунок досяг ліміту кредитів. Перевірте баланс кредитів, потім спробуйте ще раз.
- Безкоштовний план: Для створення завдання потрібен платний план. Оновіть свій план у налаштуваннях підписки, потім спробуйте ще раз.
- Name
403 - Forbidden- Description
Модерація контенту заблокувала prompt або вхідне зображення. Змініть вхідні дані, потім спробуйте ще раз.
- Name
429 - Too Many Requests- Description
Ви перевищили обмеження частоти запитів. Зачекайте, потім спробуйте ще раз. Див. Обмеження частоти.
Отримати задачу Текст у 3D
Повертає задачу Текст у 3D за її ID. Працює як для задач preview, так і для задач refine.
Request
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": null,
"consumed_credits": 20
}
Параметри
- Name
- id
- Type
- path
- Description
ID задачі з відповіді на створення.
Повертає
Приклади
У таблиці нижче наведено приклад моделі для кожного mode.
| Mode | Приклад моделі |
|---|---|
| Preview | ![]() |
| Refine | ![]() |
Видалення задачі Text to 3D
Остаточно видаляє задачу Текст у 3D, включно з її моделями та даними. Видалення не можна скасувати.
Request
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 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.
Список завдань Текст у 3D
Повертає список ваших завдань Текст у 3D.
Request
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": null,
"consumed_credits": 20
}
]
Параметри
- 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 з розбиттям на сторінки.
Потокова передача завдання Текст у 3D
Передає оновлення завдання Текст у 3D у вигляді Server-Sent Events (SSE).
Request
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.
// 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",
"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": null,
"consumed_credits": 20
}
Параметри
- Name
- id
- Type
- path
- Description
ID завдання з відповіді на створення.
Повертає
Потік об'єктів завдання Текст у 3D у вигляді Server-Sent Events.
Кожна подія містить повний об'єкт завдання, у тому самому форматі, що й повертає кінцева точка Get. Поки завдання має статус PENDING або IN_PROGRESS, його поля результату ще не мають значень.
Об'єкт завдання Text to 3D
Об'єкт завдання Text to 3D описує одне завдання, що генерує 3D модель на основі текстового prompt. Він містить статус, progress і файли моделі, коли завдання завершується успішно. Текст у 3D має два етапи: preview і refine. Завдання preview генерує 3D модель лише з сіткою, а завдання refine генерує текстуровану 3D модель на основі результату preview.
Властивості
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": null,
"consumed_credits": 20
}
- Name
- id
- Type
- string
- Description
ID завдання. Розглядайте його як непрозорий рядок і не покладайтеся на його формат.
- Name
- type
- Type
- string
- Description
Тип завдання:
text-to-3d-previewдля завдання preview абоtext-to-3d-refineдля завдання refine.
- Name
- model_urls
- Type
- object
- Description
URL-адреси для завантаження згенерованої 3D моделі, по одній для кожного формату файлу. Якщо завдання не згенерувало певний формат, ключ для нього відсутній, а не містить порожній рядок.
- 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. Присутній, лише якщо
target_formatsвключає3mf.
- Name
- prompt
- Type
- string
- Description
prompt, який ви надіслали для створення завдання, без змін.
- 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
URL-адреса для завантаження зображення, яке ви надіслали для керування текстуруванням.
- Name
- thumbnail_url
- Type
- string
- Description
URL-адреса для завантаження мініатюри 3D моделі.
- Name
- alpha_thumbnail_url
- Type
- string
- Description
URL-адреса для завантаження версії
thumbnail_urlз прозорим фоном (RGBA). Присутня, лише якщо ви створили завдання зalpha_thumbnail: true, і Meshy відрендерив прозорий попередній перегляд.
- Name
- progress
- Type
- integer
- Description
Наскільки завдання виконано, у відсотках. Дорівнює
0, доки завдання не почалося, і100, коли воно успішно завершується.
- Name
- started_at
- Type
- timestamp
- Description
Час початку завдання, в мілісекундах Unix. Дорівнює
0, доки завдання не почалося.
- Name
- created_at
- Type
- timestamp
- Description
Час створення завдання, в мілісекундах Unix.
- Name
- finished_at
- Type
- timestamp
- Description
Час завершення завдання, в мілісекундах Unix. Дорівнює
0, доки завдання не завершиться.
- Name
- status
- Type
- string
- Description
Статус завдання, один з
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDабоCANCELED.
- Name
- texture_urls
- Type
- array
- Description
URL-адреси для завантаження згенерованих текстурних карт, у вигляді масиву об'єктів. Зазвичай містить один об'єкт. Кожен об'єкт має такі поля:
- Name
base_color- Type
- string
- Description
Карта базового кольору.
- Name
metallic- Type
- string
- Description
Карта металевості. Відсутня, якщо ви створили завдання з
enable_pbr: false.
- Name
normal- Type
- string
- Description
Карта нормалей. Відсутня, якщо ви створили завдання з
enable_pbr: false.
- Name
roughness- Type
- string
- Description
Карта шорсткості. Відсутня, якщо ви створили завдання з
enable_pbr: false.
- Name
emission- Type
- string
- Description
Карта випромінювання. Відсутня в будь-якому з цих випадків:
- Ви створили завдання з
enable_pbr: false. ai_modelмає значенняmeshy-6-lite,meshy-7,meshy-7.1абоlatest.texture_resolutionмає значення8k.- Завдання виконує refine для preview
meshy-t2абоmeshy-t2.5без вказанняai_model.
- Ви створили завдання з
- Name
- preceding_tasks
- Type
- integer
- Description
Кількість завдань попереду цього в черзі. Значення має сенс, лише доки завдання перебуває у статусі
PENDING.
- Name
- task_error
- Type
- object
- Description
Деталі помилки, коли завдання завершується невдало. Дорівнює
null, якщо статус неFAILED. Див. Помилки.
- Name
- consumed_credits
- Type
- integer
- Description
Кількість кредитів, витрачених завданням. Присутнє, коли статус —
PENDING,IN_PROGRESSабоSUCCEEDED. Дорівнює0для завданняFAILED, оскільки Meshy повертає кредити, якщо завдання завершується невдало.

