Text to 3D API

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

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

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

Create a Text to 3D Preview Task

Ця кінцева точка створює завдання попереднього перегляду Текст у 3D, яке генерує нетекстуровану 3D-сітку (лише геометрію) з текстового prompt. Це перший крок дворівневого робочого процесу. Після успішного завершення попереднього перегляду використайте отриманий 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).
    • 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-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
    • meshy-7 (застаріле): натомість використовуйте meshy-7.1.

    Генерація Smart Topology (model_type: smart-topology):

    • meshy-t2 (за замовчуванням): модель Smart Topology — чистіша topology, природно розділені частини, вивід у трикутниках і кількість граней, яку можна задати через target_polycount.
  • Name
    geometry_resolution
    Type
    string
    за замовчуванням standard
    Description

    Прохід генерації геометрії. 2k запускає прохід Ultra з роздільністю 2048³; 4k запускає його з роздільністю 4096³ для найтоншої деталізації поверхні.

    Доступні значення: standard, 2k, 4k

    Підтримується лише в mode 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 повертає помилку.

  • 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

    Вкажіть pose_mode для згенерованої моделі.

    Доступні значення:

    • 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 перевищує обмеження за кількістю символів.
    • Непідтримувана модель для 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

Створення завдання Text to 3D Refine

Ця кінцева точка створює завдання Text to 3D refine, яке застосовує текстуру до завершеної попередньої (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-карти (metallic, roughness, normal) на додачу до базового кольору. Карта emission також включається, коли ai_model дорівнює meshy-6, за винятком texture_resolution: 8k (карта emission не створюється). meshy-6-lite, meshy-7.1 та latest не створюють карту emission.

  • 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 карта emission не створюється.

  • 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,<ваші дані зображення, закодовані у 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; інші моделі його ігнорують.

  • 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.
  • 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.

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

Параметри

  • Name
    id
    Type
    path
    Description

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

Повертає

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

Приклади

ModeПриклад моделі
PreviewPreview model
RefineRefined model

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, для якої потрібно отримувати потокові оновлення.

Повертає

Повертає потік об'єктів задачі Text to 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-моделі з текстового вводу. Існує два етапи Text to 3D API: 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

    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

    Застаріле; замість цього читайте 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-адреса для завантаження мініатюри файлу моделі.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL-адреса для завантаження версії thumbnail_url із прозорим фоном (RGBA). Присутня лише тоді, коли завдання було створено з alpha_thumbnail: true і прозорий попередній перегляд було успішно відрендерено; в іншому випадку це поле пропускається.

  • Name
    video_url
    Type
    string
    ⚠ застарілий
    Description

    URL-адреса для завантаження попереднього відео. Буде видалено в одному з майбутніх релізів.

  • 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-6-lite, ця властивість буде пропущена.

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