Ремеш API

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

POST/openapi/v1/remesh

Create a Remesh Task

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

Завдання виконується у фоновому режимі. Інформацію про те, скільки це зазвичай триває, див. у розділі Час обробки.

Для конвертації формату та зміни розміру використовуйте спеціалізовані 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.
Максимальний розмір файлу: 400 МБ для URL-адреси http або https, 100 МБ для data: URI.
Файл GLB, glTF, FBX або OBJ розміром понад 100 МБ може містити не більше 10 000 000 граней. Грані рахуються як трикутники: чотирикутник рахується як 2, а сітка, намальована кілька разів, рахується один раз за кожну копію. Для файлів понад 100 МБ файл FBX повинен бути у форматі бінарного FBX 7.1 або новішого, а файл GLB або glTF не повинен використовувати стиснення Draco.

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.
target_formats має бути вказано, якщо convert_format_only встановлено у значення true.

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.
- Файл моделі занадто великий: файл model_url перевищує 400 МБ (URL-адреса http або https) або 100 МБ (data: URI).
- Забагато граней: файл model_url перевищує 100 МБ і має більше ніж 10 000 000 граней. Зменшіть кількість граней і надішліть файл знову.
- ASCII FBX понад 100 МБ: файл model_url є ASCII FBX розміром понад 100 МБ. Надішліть його як бінарний FBX або GLB.
- Нечитабельний файл моделі: файл model_url перевищує 100 МБ, і його заголовок неможливо прочитати, наприклад, стиснутий Draco файл GLB або glTF, або бінарний FBX старіший за 7.1.
- Заголовок моделі занадто складний: файл model_url перевищує 100 МБ, і його заголовок містить забагато сіток, вузлів або записів для перевірки. Зменшіть кількість об'єктів у файлі та надішліть його знову.
- Недійсна 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
}