Remesh API

Remesh API дозволяє виконувати ремеш та експортувати наявні 3D-моделі, згенеровані іншими API Meshy (наприклад, Зображення у 3D або Текст у 3D), у різні формати. У цьому розділі наведено детальну інформацію про використання Remesh API.

POST/openapi/v1/remesh

Створення завдання Ремешу

Ця кінцева точка створює нове завдання ремешу.

Для конвертації формату та зміни розміру використовуйте спеціальні Convert API та Resize API. Наведені нижче застарілі параметри продовжуватимуть працювати, але для нових інтеграцій ми рекомендуємо нові кінцеві точки.

Параметри

Обов'язковим є лише один із параметрів input_task_id або model_url. Якщо надано обидва, пріоритет має input_task_id.

Name
input_task_id
Type
string
Обов'язковий
Description
ID завершеного завдання Зображення у 3D або Текст у 3D, яке ви хочете піддати ремешу. Це завдання має бути одним із наступних: Text to 3D Preview, Text to 3D Refine, Image to 3D або Retexture. Крім того, воно повинно мати статус SUCCEEDED.

Name
model_url
Type
string
Обов'язковий
Description
Будь ласка, надайте 3D-модель для ремешу Meshy через загальнодоступне URL-посилання або data URI. Підтримувані формати: .glb, .gltf, .obj, .fbx, .stl.
Для Data URI використовуйте MIME type: application/octet-stream.

Name
target_formats
Type
string[]
за замовчуванням ["glb"]
Description
Список цільових форматів для моделі після ремешу. Якщо не вказано, генерується лише GLB.
Доступні значення: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
за замовчуванням triangle
Description
Вкажіть topology згенерованої моделі.
Доступні значення:
- quad: Створити сітку з переважанням чотирикутників.
- triangle: Створити децимовану трикутну сітку.
Name
target_polycount
Type
integer
за замовчуванням 30,000
Description
Вкажіть цільову кількість полігонів у згенерованій моделі. Фактична кількість полігонів може відрізнятися від цільової залежно від складності геометрії.
Допустимий діапазон значень залежить від рівня користувача:
- від 100 до 300 000 (включно)
Name
decimation_mode
Type
integer
Description
Увімкніть адаптивну децимацію, встановивши рівень кількості полігонів. Якщо встановлено, target_polycount ігнорується.
Доступні значення:
- 1: Адаптивно — ультра кількість полігонів.
- 2: Адаптивно — висока кількість полігонів.
- 3: Адаптивно — середня кількість полігонів.
- 4: Адаптивно — низька кількість полігонів.
Name
resize_height
Type
number
⚠ застарілий
за замовчуванням 0
Description
Змінити розмір моделі до певної висоти, виміряної в метрах. Ми рекомендуємо натомість використовувати спеціальний Resize API.
auto_size, resize_height та resize_longest_side є взаємовиключними.
Name
resize_longest_side
Type
number
⚠ застарілий
за замовчуванням 0
Description
Змінити розмір моделі так, щоб найдовший вимір обмежувальної рамки дорівнював вказаному значенню в метрах. Ми рекомендуємо натомість використовувати спеціальний Resize API.
auto_size, resize_height та resize_longest_side є взаємовиключними.
Name
auto_size
Type
boolean
⚠ застарілий
за замовчуванням false
Description
Якщо встановлено значення true, сервіс використовує AI-зір для автоматичної оцінки реальної висоти об'єкта та відповідної зміни розміру моделі. Ми рекомендуємо натомість використовувати спеціальний Resize API.
auto_size, resize_height та resize_longest_side є взаємовиключними.

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

Name
origin_at
Type
string
⚠ застарілий
за замовчуванням bottom
Description
Позиція початку координат. Ми рекомендуємо натомість використовувати спеціальний Resize API.
Доступні значення: bottom, center.

Name
convert_format_only
Type
boolean
⚠ застарілий
Description
Якщо true, сервіс лише змінить формат вхідного файлу моделі, ігноруючи інші вхідні дані, такі як topology, resize_height та target_polycount. Ми рекомендуємо натомість використовувати спеціальний Convert API.
Якщо convert_format_only встановлено на true, необхідно вказати target_formats.

Name
alpha_thumbnail
Type
boolean
за замовчуванням false
Description
Якщо встановлено значення true, завдання додатково рендерить версію попереднього перегляду з прозорим фоном (RGBA) та повертає її як alpha_thumbnail_url у відповіді GET. Наявне поле thumbnail_url залишається без змін.

Повертає

Властивість result відповіді містить id щойно створеного завдання ремешу.

Режими збою

Name
400 - Bad Request
Description
Запит неприйнятний. Поширені причини:
- Відсутній параметр: необхідно вказати model_url або input_task_id.
- Недійсне вхідне завдання: input_task_id повинен посилатися на успішне завдання від підтримуваної моделі.
- Недійсний формат моделі: model_url вказує на файл із непідтримуваним розширенням.
- Недоступне URL-посилання: не вдалося завантажити model_url.
- Недійсна topology: параметр topology є недійсним.
- Взаємовиключні параметри: auto_size і resize_height не можуть бути встановлені одночасно.
Name
401 - Unauthorized
Description
Помилка автентифікації. Будь ласка, перевірте свій API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти.

Request

POST

/openapi/v1/remesh

# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/remesh/:id

Отримати завдання Ремешу

Ця кінцева точка отримує завдання ремешу за його ID.

Параметри

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

Повертає

Об'єкт завдання Ремешу.

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

DELETE/openapi/v1/remesh/:id

Видалити завдання Ремешу

Ця кінцева точка остаточно видаляє завдання ремешу, включаючи всі пов'язані моделі та дані. Ця дія незворотна.

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

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

Повертає

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

Request

DELETE

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/remesh

Список завдань Ремешу

Ця кінцева точка дозволяє отримати список завдань Ремешу.

Параметри

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: Сортування за часом створення у порядку спадання.

Повертає

Повертає пагінований список об'єктів завдання Ремешу.

Request

GET

/openapi/v1/remesh

curl https://api.meshy.ai/openapi/v1/remesh?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]

GET/openapi/v1/remesh/:id/stream

Потокова передача завдання Ремешу

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

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор завдання Ремешу для потокової передачі.

Повертає

Повертає потік об'єктів завдання Ремешу у вигляді Server-Sent Events.

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

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/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": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

Об'єкт задачі Ремешу

Об'єкт задачі Ремешу представляє одиницю роботи, яку Meshy використовує для ремешування та експорту наявної 3D моделі в різні формати. Об'єкт має такі властивості:

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор задачі. Хоча як деталь реалізації ми використовуємо k-сортований UUID для ідентифікаторів задач, вам не слід робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип задачі Ремешу. Значення — remesh.
Name
model_urls
Type
object
Description
Посилання для завантаження текстурованого файлу 3D моделі, згенерованого Meshy. Властивість для формату буде відсутня, якщо цей формат не був згенерований, замість повернення порожнього рядка.
- Name
  glb
  Type
  string
  Description
  Посилання для завантаження файлу GLB.
- Name
  fbx
  Type
  string
  Description
  Посилання для завантаження файлу FBX.
- Name
  obj
  Type
  string
  Description
  Посилання для завантаження файлу OBJ.
- Name
  usdz
  Type
  string
  Description
  Посилання для завантаження файлу USDZ.
- Name
  blend
  Type
  string
  Description
  Посилання для завантаження файлу Blender.
- Name
  stl
  Type
  string
  Description
  Посилання для завантаження файлу STL.
- Name
  3mf
  Type
  string
  Description
  Посилання для завантаження файлу 3MF. Присутнє лише якщо 3mf було запитано через target_formats.
Name
thumbnail_url
Type
string
Description
Посилання для завантаження попереднього зображення, відрендереного з ремешованої моделі.
Name
alpha_thumbnail_url
Type
string
Description
Посилання для завантаження версії thumbnail_url із прозорим фоном (RGBA). Присутнє лише якщо задачу було створено з alpha_thumbnail: true і прозоре попереднє зображення було успішно відрендерено; в іншому випадку це поле відсутнє.
Name
progress
Type
integer
Description
Прогрес задачі. Якщо задача ще не розпочата, ця властивість дорівнюватиме 0. Коли задача завершиться успішно, це значення стане 100.
Name
status
Type
string
Description
Статус задачі. Можливі значення: PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Кількість попередніх задач.
Значення цього поля має сенс лише якщо статус задачі — PENDING.
Name
created_at
Type
timestamp
Description
Мітка часу створення задачі, в мілісекундах.
Name
started_at
Type
timestamp
Description
Мітка часу початку виконання задачі, в мілісекундах. Якщо задача ще не розпочата, ця властивість дорівнюватиме 0.
Name
finished_at
Type
timestamp
Description
Мітка часу завершення задачі, в мілісекундах. Якщо задача ще не завершена, ця властивість дорівнюватиме 0.
Name
task_error
Type
object
Description
Деталі помилки для невдалих задач. Дивіться Помилки для повного опису об'єкта task_error.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, витрачених на цю задачу. Присутнє, коли статус задачі — PENDING, IN_PROGRESS або SUCCEEDED. Повертає 0 для задач зі статусом FAILED (кредити повертаються у разі невдачі).

Example Remesh Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}