API Ремеш

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

POST/openapi/v1/remesh

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

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

Для конвертації формату та зміни розміру використовуйте спеціальні API Конвертувати і 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
Змініть розмір моделі до певної висоти, виміряної в метрах. Натомість ми рекомендуємо використовувати спеціальний API Змінити розмір.
auto_size, resize_height і resize_longest_side є взаємовиключними.
Name
resize_longest_side
Type
number
⚠ застарілий
за замовчуванням 0
Description
Змініть розмір моделі так, щоб найдовший вимір обмежувального блока дорівнював указаному значенню в метрах. Натомість ми рекомендуємо використовувати спеціальний API Змінити розмір.
auto_size, resize_height і resize_longest_side є взаємовиключними.
Name
auto_size
Type
boolean
⚠ застарілий
за замовчуванням false
Description
Якщо встановлено true, сервіс використовує AI-зір для автоматичної оцінки реальної висоти об’єкта та відповідної зміни розміру моделі. Натомість ми рекомендуємо використовувати спеціальний API Змінити розмір.
auto_size, resize_height і resize_longest_side є взаємовиключними.

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

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

Name
convert_format_only
Type
boolean
⚠ застарілий
Description
Якщо true, сервіс лише змінить формат вхідного файла моделі, ігноруючи інші вхідні дані, як-от topology, resize_height і target_polycount. Натомість ми рекомендуємо використовувати спеціальний 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 не вдалося завантажити.
- Недійсна 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
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
progress завдання. Якщо завдання ще не розпочато, ця властивість буде 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
}