Текст у 3D API

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

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

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

    Вкажіть 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 перевищує ліміт символів.
  • 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

Створення задачі 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 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,<ваші base64-закодовані дані зображення>

    Текстурування за зображенням може працювати неоптимально, якщо між оригінальним asset та завантаженим зображенням є суттєві відмінності геометрії. Для керування процесом текстурування можна використовувати лише один з параметрів — texture_image_url або texture_prompt. Якщо вказано обидва параметри, за замовчуванням для текстурування моделі буде використано texture_prompt.

  • Name
    ai_model
    Type
    string
    за замовчуванням inherited from the preview task
    Description

    Ідентифікатор моделі, яку слід використовувати для refine. Доступні значення: meshy-5, meshy-6, meshy-7, latest (Meshy 7).

    Пропустіть цей параметр, щоб успадкувати модель, яку використовувала задача попереднього перегляду — це забезпечує використання однієї й тієї самої моделі як для попереднього перегляду, так і для refine від початку до кінця. Передайте явне значення, щоб перевизначити це успадкування.

    Явне значення latest тут визначається так само, як і в задачі попереднього перегляду (наразі Meshy 7), тому попередній перегляд latest і його refine latest завжди використовують одну й ту саму модель текстурування.

  • Name
    moderation
    Type
    boolean
    за замовчуванням false
    Description

    Якщо встановлено значення true, вхідний контент буде автоматично перевірено на наявність потенційно шкідливого вмісту. Якщо шкідливий вміст буде виявлено, задача не перейде до етапу генерації.

    Перевірці підлягають як текст з texture_prompt, так і зображення з texture_image_url.

  • Name
    remove_lighting
    Type
    boolean
    за замовчуванням true
    Description

    Видаляє відблиски та тіні з текстури базового кольору, забезпечуючи чистіший результат, який краще підходить для користувацьких налаштувань освітлення.

    Діє лише тоді, коли ai_model дорівнює meshy-6. У meshy-7 (і 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, сервіс використовує 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, яке потрібно видалити.

Повертає

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

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

// Returns 200 Ok on success.
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

    Обмеження розміру сторінки. Максимально дозволено 50 елементів.

  • Name
    sort_by
    Type
    string
    Description

    Поле для сортування.

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

    • +created_at: Сортування за часом створення у порядку зростання.
    • -created_at: Сортування за часом створення у порядку спадання.

Повертає

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

Request

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

Response

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

      "message": ""

    },

    "consumed_credits": 20
  }
]
GET/openapi/v2/text-to-3d/:id/stream

Стрімінг завдання Text to 3D

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

Параметри

  • Name
    id
    Type
    path
    Description

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

Повертає

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

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

Request

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

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"texture_urls": [
  {
    "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
    "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
    "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
    "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
    "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
  }
],
"preceding_tasks": 0,
"task_error": {

  "message": ""

},

"consumed_credits": 20
}

Об'єкт задачі Text to 3D

Об'єкт задачі Text to 3D — це одиниця роботи, яку Meshy відстежує для генерації 3D моделі з текстового вхідного даного. Існує два етапи 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

    Відображає значення 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, і прозоре прев'ю було успішно відрендерено; в іншому разі це поле опускається.

  • 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 за Гринвічем представлена як 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 (кредити повертаються у разі невдачі).

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
}