Ремеш API

Перебудуйте сітку 3D-моделі з новою topology та кількістю граней, і експортуйте її у вибрані вами формати. Модель може походити з іншого завдання Meshy, наприклад Зображення у 3D або Текст у 3D, або з файлу моделі.

POST/openapi/v1/remesh

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

Створює завдання Ремеш. Завдання виконується у фоновому режимі. Про типову тривалість виконання завдання див. Час обробки.

Щоб конвертувати формат моделі або змінити її розмір, скористайтеся Convert API або Resize API. Застарілі параметри на цій сторінці й досі працюють, але нові інтеграції мають використовувати саме ці кінцеві точки.

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

Параметри

Name
input_task_id
Type
string
Обов'язковий
Description
Обов'язковий, якщо не надіслано model_url. ID завдання, модель якого ви хочете ремешити, наприклад завдання Текст у 3D, Зображення у 3D, Ретекстурування або Ремеш. Завдання має бути створене вами через API і мати статус SUCCEEDED.

Name
model_url
Type
string
Обов'язковий
Description
Обов'язковий, якщо не надіслано input_task_id. Модель для ремешингу у вигляді публічної URL-адреси або data URI. Якщо надіслано обидва параметри, Meshy використовує input_task_id.
Модель має бути файлом GLB, glTF, OBJ, FBX або STL розміром не більше 400 МБ за http або https URL-адресою, або 100 МБ як data URI. Для data URI використовуйте MIME type application/octet-stream.
Файл понад 100 МБ також має відповідати цим правилам:
- Файл GLB, glTF, FBX або OBJ може мати не більше 10 000 000 граней. Meshy рахує грані як трикутники, тому чотирикутник рахується як 2, а сітка, намальована більше одного разу, рахується один раз для кожної копії.
- Файл FBX має бути бінарним FBX 7.1 або новішим.
- Файл GLB або glTF не повинен використовувати стиснення Draco.

Name
target_formats
Type
string[]
за замовчуванням ["glb"]
Description
Формати файлів для генерації.
Доступні значення:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf
Name
topology
Type
string
за замовчуванням triangle
Description
Тип граней ремешованої моделі.
Доступні значення:
- quad: сітка з переважанням чотирикутників
- triangle: децимована трикутна сітка
Name
target_polycount
Type
integer
за замовчуванням 30000
Description
Бажана кількість граней, від 100 до 300000. Результат може відрізнятися від цільового значення залежно від геометрії моделі. Значення поза межами діапазону повертає 400.
Name
decimation_mode
Type
integer
Description
Адаптивна кількість граней за рівнем. Якщо встановити цей параметр, Meshy ігнорує target_polycount.
Доступні значення:
- 1: ультра
- 2: висока
- 3: середня
- 4: низька
Name
resize_height
Type
number
⚠ застарілий
за замовчуванням 0
Description
Замість цього використовуйте Resize API. Висота, до якої потрібно змінити розмір моделі, у метрах. Надсилайте не більше одного з параметрів resize_height, resize_longest_side та auto_size.
Name
resize_longest_side
Type
number
⚠ застарілий
за замовчуванням 0
Description
Замість цього використовуйте Resize API. Довжина, до якої потрібно змінити розмір найдовшої сторони обмежувального паралелепіпеда моделі, у метрах. Надсилайте не більше одного з параметрів resize_height, resize_longest_side та auto_size.
Name
auto_size
Type
boolean
⚠ застарілий
за замовчуванням false
Description
Замість цього використовуйте Resize API. Чи потрібно оцінити реальну висоту об'єкта за допомогою AI vision і змінити розмір моделі відповідно до неї. Надсилайте не більше одного з параметрів resize_height, resize_longest_side та auto_size.
Name
origin_at
Type
string
⚠ застарілий
за замовчуванням bottom
Description
Замість цього використовуйте Resize API. Куди помістити початок координат моделі: bottom або center. Значення за замовчуванням застосовується, коли ви надсилаєте resize_height, resize_longest_side або auto_size. Без жодного з них Meshy переміщує початок координат, лише якщо ви надішлете origin_at.

Name
convert_format_only
Type
boolean
⚠ застарілий
Description
Замість цього використовуйте Convert API. Чи потрібно лише конвертувати модель у target_formats. Коли встановлено true, Meshy ігнорує topology, target_polycount, decimation_mode, resize_height, resize_longest_side та auto_size, але все одно перевіряє їхні значення, тому недійсне значення поверне 400. Якщо convert_format_only: true, порожнє або null значення target_formats поверне 400.

Name
alpha_thumbnail
Type
boolean
за замовчуванням false
Description
Чи потрібно також рендерити попередній перегляд із прозорим фоном (RGBA), який повертається в alpha_thumbnail_url при отриманні завдання. thumbnail_url при цьому не змінюється.

Повернені значення

Поле result у відповіді містить ID нового завдання Ремеш.

Режими відмови

Name
400 - Bad Request
Description
Запит не може бути виконаний. Повідомлення про помилку вказує, яку саме проблему виявлено. Наприклад:
- Відсутній параметр: не надіслано ні model_url, ні input_task_id.
- Недійсне вхідне завдання: input_task_id не є успішним завданням API, або його AI-модель не підтримує ремешинг.
- Недійсний формат моделі: файл model_url має непідтримуване розширення.
- Недоступна URL-адреса: Meshy не може завантажити файл за model_url.
- Файл моделі завеликий: файл model_url перевищує 400 МБ за http- або https-адресою, або 100 МБ як data URI.
- Забагато граней: файл model_url перевищує 100 МБ і має понад 10 000 000 граней. Зменшіть кількість граней і надішліть файл знову.
- ASCII FBX понад 100 МБ: файл model_url — це ASCII FBX понад 100 МБ. Надішліть його у вигляді бінарного FBX або GLB.
- Нечитабельний файл моделі: файл model_url перевищує 100 МБ, і Meshy не може прочитати його заголовок. Наприклад, це GLB або glTF зі стисненням Draco, або бінарний FBX старіший за 7.1.
- Заголовок моделі занадто складний: файл model_url перевищує 100 МБ, і його заголовок містить забагато сіток, вузлів або записів для перевірки. Зменшіть кількість об'єктів у файлі й надішліть його знову.
- Недійсна topology: topology не дорівнює quad чи triangle.
- Взаємовиключні параметри: у запиті вказано більше одного з параметрів auto_size, resize_height та resize_longest_side. Надсилайте лише один.
Виправте запит і надішліть його знову. Див. Помилки.
Name
401 - Unauthorized
Description
API-ключ відсутній або недійсний. Перевірте заголовок Authorization.
Name
402 - Payment Required
Description
Наприклад:
- Недостатньо кредитів: на рахунку недостатньо кредитів для цього завдання, або досягнуто ліміту кредитів. Перевірте свій баланс кредитів і повторіть спробу.
- Безкоштовний план: для створення завдання потрібен платний план. Оновіть свій план у налаштуваннях підписки, а потім повторіть спробу.
Name
403 - Forbidden
Description
input_task_id вказує на барельєфну модель, яку ця кінцева точка не може ремешити. Повідомлення: This model type does not support this operation. Надішліть іншу модель.
Name
404 - Not Found
Description
input_task_id не відповідає жодному з ваших завдань. Перевірте ID завдання і надішліть запит знову.
Name
429 - Too Many Requests
Description
Перевищено обмеження частоти запитів. Зачекайте, а потім повторіть спробу. Див. Обмеження частоти.

GET/openapi/v1/remesh/:id

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

Повертає завдання Ремешу за його 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
}

Параметри

Name
id
Type
path
Description
ID завдання з відповіді на створення.

Повертає

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

DELETE/openapi/v1/remesh/:id

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

Остаточно видаляє завдання Ремешу, включно з його моделями та даними. Скасувати видалення неможливо.

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

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

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

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

Видалення завдання зі статусом PENDING повертає кредити, витрачені під час його створення.

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

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

Повертає

200 OK, коли завдання видалено, або 409 Conflict, коли завдання має статус IN_PROGRESS.

GET/openapi/v1/remesh

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

Повертає список ваших завдань Ремешу.

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

Параметри

Name
page_num
Type
integer
за замовчуванням 1
Description
Номер сторінки, яку потрібно повернути, до 255. Більше значення поверне 400.
Name
page_size
Type
integer
за замовчуванням 10
Description
Кількість завдань на сторінці, до 100.
Name
sort_by
Type
string
Description
Порядок сортування.
Доступні значення:
- +created_at: спочатку найстаріші
- -created_at: спочатку найновіші

Повертає

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

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

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

Передає оновлення завдання Ремеш у вигляді подій Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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,
}

Параметри

Name
id
Type
path
Description
ID завдання з відповіді на створення.

Повертає

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

Кожна подія містить повний об'єкт завдання в тому ж форматі, що повертає кінцева точка Get. Поки завдання має статус PENDING або IN_PROGRESS, його поля результату ще не мають значень.

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

Об'єкт завдання Ремеш описує один ремеш 3D-моделі. Він містить статус, progress та файли моделі, коли завдання завершується успішно.

Властивості

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
}

Name
id
Type
string
Description
ID завдання. Розглядайте його як непрозорий рядок і не покладайтесь на його формат.
Name
type
Type
string
Description
Тип завдання, завжди remesh.
Name
model_urls
Type
object
Description
URL-адреси для завантаження реmesh-моделі, по одній на кожен формат файлу. Формат, який завдання не згенерувало, не має ключа, замість порожнього рядка.
- 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. Присутній лише якщо target_formats включає 3mf.
Name
thumbnail_url
Type
string
Description
URL-адреса для завантаження попереднього зображення реmesh-моделі.
Name
alpha_thumbnail_url
Type
string
Description
URL-адреса для завантаження версії thumbnail_url із прозорим фоном (RGBA). Присутня лише якщо ви створили завдання з alpha_thumbnail: true, і Meshy згенерував прозорий попередній перегляд.
Name
progress
Type
integer
Description
Наскільки виконане завдання, у відсотках. Дорівнює 0, доки завдання не почалося, і 100, коли воно завершилося успішно.
Name
status
Type
string
Description
Статус завдання, один із PENDING, IN_PROGRESS, SUCCEEDED, FAILED або CANCELED.
Name
preceding_tasks
Type
integer
Description
Кількість завдань попереду цього в черзі. Значення має сенс лише поки завдання перебуває в статусі PENDING.
Name
created_at
Type
timestamp
Description
Час створення завдання, у мілісекундах Unix.
Name
started_at
Type
timestamp
Description
Час початку завдання, у мілісекундах Unix. Дорівнює 0, доки завдання не почалося.
Name
finished_at
Type
timestamp
Description
Час завершення завдання, у мілісекундах Unix. Дорівнює 0, доки завдання не завершилося.
Name
expires_at
Type
timestamp
Description
Час, коли спливає термін дії URL-адрес для завантаження завдання, у мілісекундах Unix. Дорівнює 0, доки завдання не завершилося.
Name
texture_urls
Type
array
Description
URL-адреси для завантаження текстурних карт моделі, коли завдання завершується успішно: масив об'єктів, по одному на кожен набір текстур. Кожен об'єкт має URL-адресу base_color, а також може мати URL-адреси metallic, roughness, normal, emission та metallic_roughness. Дорівнює null, доки завдання не завершилося успішно, і є порожнім масивом, коли модель не має текстурних карт.
Name
task_error
Type
object
Description
Деталі помилки, якщо завдання завершилося невдало. Див. Помилки.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, використаних завданням. Присутня, коли статус — PENDING, IN_PROGRESS або SUCCEEDED. Дорівнює 0 для завдання зі статусом FAILED, оскільки Meshy повертає кредити, коли завдання завершується невдало.