API Текст у 3D

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

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

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

Створення завдання попереднього перегляду Текст у 3D

Ця кінцева точка створює завдання попереднього перегляду Текст у 3D, яке генерує нетекстуровану 3D-сітку (лише геометрію) з текстового prompt. Це перший крок у двоетапному робочому процесі. Після успішного завершення попереднього перегляду використайте отриманий ID завдання, щоб створити завдання уточнення для текстурування. Зверніться до Об'єкта завдання Текст у 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).
- lowpoly (застаріле): Генерує низькополігональну сітку, оптимізовану для чистіших полігонів. Рекомендуємо натомість використовувати smart-topology.
Коли обрано smart-topology, параметри should_remesh та decimation_mode ігноруються, і приймається лише topology: triangle.
Коли обрано lowpoly, параметри ai_model, topology, target_polycount та should_remesh ігноруються.
Name
ai_model
Type
string
за замовчуванням latest
Description
ID моделі, яку слід використовувати. Доступні значення залежать від model_type.
Стандартна генерація (model_type: standard):
- meshy-5, meshy-6, meshy-7, latest (Meshy 7)
Генерація Smart Topology (model_type: smart-topology):
- meshy-t2 (за замовчуванням): модель Smart Topology — чистіша topology, природно розділені частини, вихід трикутниками та кількість граней, яку можна задати через target_polycount.
Name
ultra_mode
Type
boolean
за замовчуванням false
Description
Увімкнення генерації Ultra для геометрії вищої точності з дрібнішими деталями поверхні. Генерація триває довше та додає 5 кредитів.
Підтримується лише коли ai_model має значення meshy-7 (або latest), і лише в режимі preview.
Name
should_remesh
Type
boolean
за замовчуванням false (meshy-6, meshy-7), true (others)
Description
Керує тим, чи вмикати фазу ремешу. Для моделі найвищої якості рекомендуємо встановити should_remesh як false.

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

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

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

Name
symmetry_mode
Type
string
⚠ застарілий
за замовчуванням auto
Description
Застаріле. Цей параметр більше не впливає на результат.
Поле symmetry_mode керує поведінкою симетрії під час процесу генерації моделі.
Допустимі значення:
- off: Вимикає симетрію.
- auto: Автоматично визначає та застосовує симетрію на основі вхідної геометрії.
- on: Примусово застосовує симетрію під час генерації.
Name
pose_mode
Type
string
за замовчуванням ""
Description
Вказує режим пози для згенерованої моделі.
Доступні значення:
- a-pose: Генерувати модель у позі A.
- t-pose: Генерувати модель у позі T.
- "" (порожній рядок): Конкретна поза не застосовується.
Name
is_a_t_pose
Type
boolean
⚠ застарілий
за замовчуванням false
Description
Використовуйте замість цього pose_mode. Чи генерувати модель у позі A/T.
Name
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, завдання додатково рендерить версію попереднього перегляду з прозорим фоном (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 завдання новоствореного завдання Текст у 3D.

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

Name
400 - Bad Request
Description
Запит було неприйнятно опрацьовано. Поширені причини:
- Відсутній параметр: Відсутній обов'язковий параметр (наприклад, prompt, mode).
- Недійсний параметр: art_style не є одним із допустимих значень.
- Занадто довгий prompt: prompt перевищує обмеження символів.
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 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",
  "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

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

Параметри

Name
mode
Type
string
Обов'язковий
Description
Це поле слід встановити в значення "refine" при створенні задачі уточнення.
Name
preview_task_id
Type
string
Обов'язковий
Description
Ідентифікатор відповідної задачі попереднього перегляду.
Статус вказаної задачі попереднього перегляду повинен бути SUCCEEDED.
Name
enable_pbr
Type
boolean
за замовчуванням false
Description
Згенерувати PBR-карти (metallic, roughness, normal) на додаток до базового кольору. Карта випромінювання (emission map) також включається, коли ai_model дорівнює meshy-6, за винятком texture_resolution: 8k (карта випромінювання не створюється). meshy-7 (та latest) не створює карту випромінювання.
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 або 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.
Існує два способи надання зображення:
- Загальнодоступна URL-адреса: URL-адреса, доступна з публічного інтернету
- Data URI: закодоване у base64 зображення у форматі data URI. Приклад data URI: data:image/jpeg;base64,<your base64-encoded image data>
Текстурування за зображенням може працювати неоптимально, якщо існують суттєві відмінності геометрії між оригінальним асетом та завантаженим зображенням. Для керування процесом текстурування можна використовувати лише один параметр: texture_image_url або texture_prompt. Якщо надано обидва параметри, для текстурування моделі за замовчуванням буде використано texture_prompt.
Name
ai_model
Type
string
за замовчуванням latest
Description
Ідентифікатор моделі, яка використовується для уточнення. Доступні значення: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
latest тут розрізняється так само, як і в задачі попереднього перегляду (наразі Meshy 7), тому попередній перегляд latest та його уточнення 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 (та latest) параметр приймається, але ігнорується.
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, сервіс використовує комп'ютерний зір ШІ для автоматичної оцінки реальної висоти об'єкта та відповідно змінює розмір моделі. Початок координат за замовчуванням буде 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
Запит було неприйнято. Поширені причини:
- Недійсний ідентифікатор задачі: preview_task_id недійсний або не існує.
- Задача не готова: задача попереднього перегляду ще не завершилася успішно.
- Невідповідність моделі: модель ШІ задачі попереднього перегляду несумісна із запитаною моделлю уточнення.
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

Отримання завдання "Текст у 3D"

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

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

Параметри

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

Повертає

Відповідь містить об'єкт завдання "Текст у 3D". Перевірте розділ Об'єкт завдання "Текст у 3D" для деталей.

Приклади

Режим	Зразок моделі
Попередній перегляд
Уточнення

Запит

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

Відповідь

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

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

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

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

Повертає

Повертає 200 OK у разі успіху.

Запит

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

Відповідь

// Returns 200 Ok on success.

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

Перелік завдань Текст у 3D

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

Параметри

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

Повертає

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

Запит

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

Відповідь

[
  {
    "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

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

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

Параметри

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

Повертає

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

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

Запит

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

Потік відповіді

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

Об'єкт завдання "Текст у 3D"

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

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

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор для завдання. Хоча ми використовуємо k-сортувальний UUID для ідентифікаторів завдань як деталь реалізації, ви не повинні робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання "Текст у 3D". Можливі значення: text-to-3d-preview для завдань етапу preview та text-to-3d-refine для завдань етапу refine.
Name
model_urls
Type
object
Description
Завантажуване URL-адреса до файлу текстурованої 3D моделі, створеної Meshy. Властивість для формату буде пропущено, якщо формат не створено, замість повернення порожнього рядка.
- Name
  glb
  Type
  string
  Description
  Завантажуване URL-адреса до файлу GLB.
- Name
  fbx
  Type
  string
  Description
  Завантажуване URL-адреса до файлу FBX.
- Name
  usdz
  Type
  string
  Description
  Завантажуване URL-адреса до файлу USDZ.
- Name
  obj
  Type
  string
  Description
  Завантажуване URL-адреса до файлу OBJ.
- Name
  mtl
  Type
  string
  Description
  Завантажуване URL-адреса до файлу MTL.
- Name
  stl
  Type
  string
  Description
  Завантажуване URL-адреса до файлу STL.
- Name
  3mf
  Type
  string
  Description
  Завантажуване URL-адреса до файлу 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
Відображає значення ultra_mode, з яким було створено завдання preview. Присутнє лише для завдань preview meshy-7 (або latest), які явно встановили ultra_mode; інакше пропущено.
Name
texture_image_url
Type
string
Description
Завантажуване URL-адреса до зображення текстури, яке використовувалося для керування процесом текстурування.
Name
thumbnail_url
Type
string
Description
Завантажуване URL-адреса до зображення мініатюри файлу моделі.
Name
alpha_thumbnail_url
Type
string
Description
Завантажуване URL-адреса до версії thumbnail_url з прозорим фоном (RGBA). Присутнє лише тоді, коли завдання було створено з alpha_thumbnail: true і прозорий preview було успішно відтворено; інакше це поле пропущено.
Name
video_url
Type
string
⚠ застарілий
Description
Завантажуване URL-адреса до відео preview. Буде видалено в майбутньому випуску.
Name
progress
Type
integer
Description
Прогрес завдання. Якщо завдання ще не розпочато, це властивість буде 0. Після успішного завершення завдання це значення стане 100.
Name
started_at
Type
timestamp
Description
Мітка часу, коли завдання було розпочато, у мілісекундах. Якщо завдання ще не розпочато, це властивість буде 0.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року за UTC, відповідно до стандарту RFC 3339. Наприклад, п'ятниця, 1 вересня 2023 року, 12:00:00 GMT представлена як 1693569600000. Це стосується всіх міток часу в Meshy API.
Name
created_at
Type
timestamp
Description
Мітка часу, коли завдання було створено, у мілісекундах.
Name
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
  Завантажуване URL-адреса до зображення карти базового кольору.
- Name
  metallic
  Type
  string
  Description
  Завантажуване URL-адреса до зображення металевої карти.
  Якщо завдання створено з enable_pbr: false, це властивість буде пропущено.
- Name
  normal
  Type
  string
  Description
  Завантажуване URL-адреса до зображення карти нормалей.
  Якщо завдання створено з enable_pbr: false, це властивість буде пропущено.
- Name
  roughness
  Type
  string
  Description
  Завантажуване URL-адреса до зображення карти шорсткості.
  Якщо завдання створено з enable_pbr: false, це властивість буде пропущено.
- Name
  emission
  Type
  string
  Description
  Завантажуване URL-адреса до зображення карти емісії.
  Якщо завдання створено з enable_pbr: false, або ai_model є meshy-5, це властивість буде пропущено.
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 (кредити повертаються у разі невдачі).

Приклад об’єкта завдання "Текст у 3D"

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