Resize API

Змінити розмір 3D-моделі до реального розміру в метрах. Встановіть її висоту або довжину найдовшої сторони, або дозвольте Meshy оцінити реальну висоту об’єкта.

POST/openapi/v1/resize

Створення завдання Resize

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

Request

POST

/openapi/v1/resize

# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

Response

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

Параметри

Name
input_task_id
Type
string
Обов'язковий
Description
Обов'язковий, якщо не надіслано model_url. ID завдання, яке створило 3D-модель, наприклад завдання Text to 3D, Image to 3D, Remesh або Retexture. Завдання повинно походити з API та мати статус SUCCEEDED. Meshy повертає змінену за розміром модель у вигляді файлу GLB.

Name
model_url
Type
string
Обов'язковий
Description
Обов'язковий, якщо не надіслано input_task_id. Модель для зміни розміру у вигляді публічного URL або data URI. Якщо надіслано обидва, Meshy використовує input_task_id.
Модель повинна бути файлом GLB, glTF, OBJ, FBX або STL розміром не більше 400 МБ за URL http чи https, або 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.
Файл GLB, OBJ, FBX або STL зберігає свій формат у результаті. Файл .gltf або data URI повертається як GLB.

Надішліть рівно один з параметрів resize_height, resize_longest_side або auto_size. Якщо не надіслати жодного з них або надіслати більше одного, повертається 400.

Name
resize_height
Type
number
Description
Нова висота моделі в метрах, більша за 0. Від'ємне значення повертає 400.

Name
resize_longest_side
Type
number
Description
Нова довжина найдовшої сторони моделі в метрах, більша за 0. Від'ємне значення повертає 400. Meshy зберігає співвідношення сторін моделі.

Name
auto_size
Type
boolean
Description
Чи оцінювати реальну висоту об'єкта за допомогою AI-зору та змінювати розмір моделі відповідно до неї. Якщо не вказано origin_at, Meshy розміщує початок координат знизу.

Name
origin_at
Type
string
за замовчуванням bottom
Description
Де розмістити початок координат моделі після зміни розміру: bottom або center.

Повертає

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

Режими збою

Name
400 - Bad Request
Description
Запит не може бути виконаний. Повідомлення про помилку вказує, яку проблему виявлено. Наприклад:
- Відсутній параметр: не надіслано ні model_url, ні input_task_id.
- Відсутній режим зміни розміру: не надіслано жодного з resize_height, resize_longest_side та auto_size.
- Взаємовиключні параметри: запит містить більше одного з resize_height, resize_longest_side та auto_size. Надішліть лише один.
- Від'ємний розмір: resize_height або resize_longest_side є від'ємним.
- Недійсне вхідне завдання: input_task_id не є успішним завданням API з файлом моделі.
- Недійсний формат моделі: файл model_url має непідтримуване розширення.
- Недоступний URL: Meshy не може завантажити файл 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 МБ, і Meshy не може прочитати його заголовок. Наприклад, це GLB чи glTF, стиснутий за допомогою Draco, або бінарний FBX старіший за 7.1.
- Заголовок моделі занадто складний: файл model_url перевищує 100 МБ, і його заголовок містить забагато сіток, вузлів або записів для перевірки. Зменшіть кількість об'єктів у файлі, потім надішліть його знову.
Виправте запит, потім надішліть його знову. Див. Помилки.
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/resize/:id

Отримати завдання Змінити розмір

Повертає завдання Змінити розмір за його ID.

Request

GET

/openapi/v1/resize/:id

curl https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Параметри

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

Повертає

Об'єкт завдання Змінити розмір.

DELETE/openapi/v1/resize/:id

Видалення задачі Resize

Остаточно видаляє задачу Resize, включно з її моделями та даними. Видалення не можна скасувати.

Request

DELETE

/openapi/v1/resize/:id

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/resize/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/resize

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

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

Request

GET

/openapi/v1/resize

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "resize",
    "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]

Параметри

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/resize/:id/stream

Стрімити задачу Змінити розмір

Стрімить оновлення задачі Змінити розмір у вигляді Server-Sent Events (SSE).

Request

GET

/openapi/v1/resize/:id/stream

curl -N https://api.meshy.ai/openapi/v1/resize/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Параметри

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

Повертає

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

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

Об'єкт завдання Resize

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

Властивості

Name
id
Type
string
Description
ID завдання. Розглядайте його як непрозорий рядок і не покладайтеся на його формат.
Name
type
Type
string
Description
Тип завдання, завжди resize.
Name
model_urls
Type
object
Description
URL для завантаження файлу моделі зі зміненим розміром. Для input_task_id файл завжди у форматі GLB. Для model_url файл GLB, OBJ, FBX або STL зберігає свій формат, а файл .gltf або Data URI повертається у форматі GLB.
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
Кількість кредитів, витрачених на завдання, що дорівнює 1 для завдання Resize. Дорівнює 0 для завдання зі статусом FAILED.