Ремеш API

Ремеш API дозволяє виконувати ремеш та експортувати існуючі 3D-моделі, згенеровані іншими API Meshy (наприклад, Зображення у 3D або Текст у 3D), у різні формати. У цьому розділі наведено детальну інформацію про використання Ремеш 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, Зображення у 3D або Ретекстурування. Крім того, воно повинно мати статус 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, сервіс використовує ШІ-зір для автоматичної оцінки реальної висоти об'єкта та відповідної зміни розміру моделі. Ми рекомендуємо натомість використовувати спеціальний 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 завдання ремешу, яке потрібно видалити.

Статус завдання

Завдання, яке ще перебуває у статусі PENDING, видаляється, а кредити, витрачені під час створення, повертаються.

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

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

Повертає

Повертає 200 OK у разі успіху, або 409 Conflict, коли завдання перебуває у статусі IN_PROGRESS.

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

// 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/v1/remesh

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

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

Параметри

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

Повертає

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

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

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

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

Властивості

Name
id
Type
string
Description
Унікальний ідентифікатор завдання. Хоча в якості деталі реалізації ми використовуємо k-сортований UUID для ідентифікаторів завдань, вам не слід робити жодних припущень щодо формату id.
Name
type
Type
string
Description
Тип завдання Ремеш. Значення — remesh.
Name
model_urls
Type
object
Description
URL-адреса для завантаження текстурованого файлу 3D-моделі, згенерованого Meshy. Властивість для формату буде відсутня, якщо формат не було згенеровано, замість повернення порожнього рядка.
- Name
  glb
  Type
  string
  Description
  URL-адреса для завантаження файлу GLB.
- Name
  fbx
  Type
  string
  Description
  URL-адреса для завантаження файлу FBX.
- Name
  obj
  Type
  string
  Description
  URL-адреса для завантаження файлу OBJ.
- Name
  usdz
  Type
  string
  Description
  URL-адреса для завантаження файлу USDZ.
- Name
  blend
  Type
  string
  Description
  URL-адреса для завантаження файлу Blender.
- Name
  stl
  Type
  string
  Description
  URL-адреса для завантаження файлу STL.
- Name
  3mf
  Type
  string
  Description
  URL-адреса для завантаження файлу 3MF. Присутнє лише тоді, коли 3mf було запитано через target_formats.
Name
thumbnail_url
Type
string
Description
URL-адреса для завантаження попереднього зображення, відрендереного з ремешованої моделі.
Name
alpha_thumbnail_url
Type
string
Description
URL-адреса для завантаження версії 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
}