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
Ідентифікатор завершеного завдання Зображення у 3D або Текст у 3D, яке ви бажаєте ремешити. Це завдання має бути одним з наступних: Текст у 3D Попередній перегляд, Текст у 3D Уточнення, Зображення у 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, сервіс використовує AI vision для автоматичної оцінки реальної висоти об'єкта та відповідно змінює розмір моделі. Ми рекомендуємо використовувати спеціальний 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 не може бути завантажений.
- Недійсна topology: Параметр topology є недійсним.
- Взаємовиключні параметри: auto_size та resize_height не можуть бути встановлені одночасно.
Name
401 - Unauthorized
Description
Автентифікація не вдалася. Будь ласка, перевірте ваш API-ключ.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
429 - Too Many Requests
Description
Ви перевищили ваше обмеження частоти.

Запит

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

Відповідь

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

GET/openapi/v1/remesh/:id

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

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

Параметри

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

Повертає

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

Запит

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

Відповідь

{
  "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
Ідентифікатор завдання ремеш для видалення.

Повертає

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

Запит

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

Відповідь

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

Повертає

Повертає список з пагінацією Об'єктів Завдань Ремеш.

Запит

GET

/openapi/v1/remesh

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

Відповідь

[
  {
    "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.

Запит

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
Прогрес завдання. Якщо завдання ще не розпочато, ця властивість буде 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 (кредити повертаються у випадку невдачі).

Приклад Об'єкта Завдання Ремеш

{
  "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
}