Текст у 3D API

Генеруйте 3D-моделі з текстових запитів у власному додатку.

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

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

Create a Text to 3D preview task

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

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

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"
}

Параметри

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-topology Meshy ігнорує should_remesh і decimation_mode, і приймає лише topology: triangle.
Name
ai_model
Type
string
за замовчуванням latest
Description
ШІ-модель, яка генерує 3D-модель. Доступні значення залежать від 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: чистіша topology, нативно розділені частини, трикутний вивід і кількість граней, яку ви встановлюєте через target_polycount
- meshy-t2.5 (за замовчуванням): чіткіша деталізація для ігрових asset'ів, трикутний вивід і кількість граней, яку ви встановлюєте через target_polycount
Name
geometry_resolution
Type
string
за замовчуванням standard
Description
Прохід генерації геометрії. Застосовується лише до попередніх завдань. Refine із цим параметром повертає 400.
Доступні значення:
- standard
- 2k: запускає прохід 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_model meshy-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_model meshy-t2 або meshy-t2.5. Meshy генерує модель із цією кількістю граней напряму. Ремеш не виконується, і should_remesh не потрібен.
У наступній таблиці показано діапазон і значення за замовчуванням для кожного випадку:
Випадок Діапазон За замовчуванням
Ремеш 100 – 300000 30000
meshy-t2 100 – 15000 4000
meshy-t2.5 100 – 30000 15000
Значення поза діапазоном повертає 400.

Випадок	Діапазон	За замовчуванням
Ремеш	`100` – `300000`	`30000`
`meshy-t2`	`100` – `15000`	`4000`
`meshy-t2.5`	`100` – `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ застарілий
за замовчуванням auto
Description
Не вказуйте цей параметр. Він не впливає на вивід.
Доступні значення:
- off: вимикає симетрію
- auto: застосовує симетрію на основі вхідної геометрії
- on: примусово застосовує симетрію під час генерації
Name
pose_mode
Type
string
за замовчуванням ""
Description
Поза згенерованої моделі.
Доступні значення:
- a-pose: поза A
- t-pose: поза T
- "" (порожній рядок): без конкретної пози
Name
is_a_t_pose
Type
boolean
⚠ застарілий
за замовчуванням false
Description
Натомість надішліть pose_mode. Чи генерувати модель у позі A чи у позі T.
Name
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, який генерується лише за запитом.
Доступні значення:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
alpha_thumbnail
Type
boolean
за замовчуванням false
Description
Чи також рендерити попередній перегляд із прозорим фоном (RGBA), що повертається в alpha_thumbnail_url при отриманні завдання. thumbnail_url не змінюється.
Name
auto_size
Type
boolean
за замовчуванням false
Description
Чи оцінювати реальну висоту об'єкта за допомогою ШІ-зору та змінювати розмір моделі відповідно до неї. 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
Ви перевищили обмеження частоти. Зачекайте, потім повторіть спробу. Див. Обмеження частоти.

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

Create a Text to 3D refine task

Створює завдання Refine для Текст у 3D, яке текстурує сітку завершеного preview-завдання. Надішліть ID успішного preview-завдання як preview_task_id. Див. Створення preview-завдання Текст у 3D. Це другий крок двоетапного робочого процесу.

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

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
}'

# 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_model meshy-6 Meshy також генерує 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×2048
- 4k: 4096×4096
- 8k: 8192×8192
Вища роздільна здатність дозволяє відтворити більше деталей поверхні. 4k і 8k потребують ai_model meshy-6, meshy-7.1 або latest. З meshy-n1 вони повертають 400. При 8k Meshy не генерує 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-n1 Meshy текстурує, використовуючи це зображення як вигляд спереду.
Текстурування за зображенням може працювати некоректно, якщо форма на зображенні значно відрізняється від моделі.
Name
ai_model
Type
string
за замовчуванням inherited from the preview task
Description
AI-модель, яка текстурує сітку.
Доступні значення:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-n1: 2K-текстура базового кольору лише за референсним зображенням. Без текстового prompt, без PBR-карт, без 4K чи 8K.
- meshy-7 (застаріле): замість цього надсилайте meshy-7.1
Залиште порожнім, щоб використати модель preview-завдання, тоді preview і його refine виконуються на тій самій моделі від початку до кінця. Надішліть значення, щоб перевизначити її. Явне значення latest розв'язується так само, як і для preview-завдання, тож latest preview і його latest refine завжди використовують ту саму модель текстурування.
З meshy-n1 Meshy текстурує за texture_image_url. Якщо його не надіслано, Meshy використовує референсне зображення, яке зберігає preview meshy-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, який генерується лише за окремим запитом.
Доступні значення:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
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-n1 preview має більше ніж 7 999 999 трикутників. Виконайте refine з іншою ai_model.
- Непідтримувана опція для Meshy N1: ai_model: meshy-n1 надіслано з однією з таких опцій:
  - texture_prompt
  - enable_pbr: true
  - texture_resolution значенням 4k або 8k
  - hd_texture: true без texture_resolution
  - remove_lighting: true
Виправте запит і надішліть його знову. Див. Помилки.
Name
401 - Unauthorized
Description
API-ключ відсутній або недійсний. Перевірте заголовок Authorization.
Name
402 - Payment Required
Description
Наприклад:
- Недостатньо кредитів: На рахунку недостатньо кредитів для цього завдання, або рахунок досяг ліміту кредитів. Перевірте баланс кредитів, потім спробуйте ще раз.
- Безкоштовний план: Для створення завдання потрібен платний план. Оновіть свій план у налаштуваннях підписки, потім спробуйте ще раз.
Name
403 - Forbidden
Description
Модерація контенту заблокувала prompt або вхідне зображення. Змініть вхідні дані, потім спробуйте ще раз.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти запитів. Зачекайте, потім спробуйте ще раз. Див. Обмеження частоти.

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

Отримати задачу Текст у 3D

Повертає задачу Текст у 3D за її ID. Працює як для задач 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": null,

  "consumed_credits": 20
}

Параметри

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

Повертає

Об'єкт задачі Текст у 3D.

Приклади

У таблиці нижче наведено приклад моделі для кожного mode.

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

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

Видалення задачі Text to 3D

Остаточно видаляє задачу Текст у 3D, включно з її моделями та даними. Видалення не можна скасувати.

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 keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

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

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

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

Видалення задачі зі статусом PENDING повертає кредити, витрачені під час її створення.

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

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

Повертає

200 OK, коли задачу видалено, або 409 Conflict, коли задача має статус IN_PROGRESS.

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

Список завдань Текст у 3D

Повертає список ваших завдань Текст у 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": 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 з розбиттям на сторінки.

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

Потокова передача завдання Текст у 3D

Передає оновлення завдання Текст у 3D у вигляді Server-Sent Events (SSE).

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.
// 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 повертає кредити, якщо завдання завершується невдало.