API Змінити розмір

API Змінити розмір дозволяє змінювати розмір наявних 3D моделей до реальних розмірів. Ви можете вказати точну висоту, обмеження за найдовшою стороною, або дозволити ШІ автоматично визначити відповідний розмір.

POST/openapi/v1/resize

Створення завдання на зміну розміру

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

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

Параметри

Потрібен лише один із параметрів input_task_id або model_url. Якщо вказано обидва, input_task_id має пріоритет.

Name
input_task_id
Type
string
Обов'язковий
Description
ID завершеного завдання Meshy, модель якого ви бажаєте змінити за розміром. Завдання повинно мати статус SUCCEEDED. Вихідним форматом буде GLB.

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

Потрібен рівно один режим зміни розміру: resize_height, resize_longest_side або auto_size. Ці три параметри є взаємовиключними.

Name
resize_height
Type
number
Description
Змінити розмір моделі до певної висоти, виміряної в метрах.

Name
resize_longest_side
Type
number
Description
Змінити розмір моделі так, щоб її найдовша сторона відповідала цьому значенню, виміряному в метрах. Співвідношення сторін зберігається.

Name
auto_size
Type
boolean
Description
Якщо встановлено true, сервіс використовує AI vision для автоматичної оцінки реальної висоти об'єкта та відповідної зміни розміру моделі. Початок координат за замовчуванням буде bottom, якщо origin_at явно не вказано.

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

Повертає

Властивість result у відповіді містить id щойно створеного завдання на зміну розміру.

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

400 - Bad Request

Запит було неприйнятно. Поширені причини:

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

401 - Unauthorized

Автентифікація не вдалася. Перевірте свій API-ключ.

402 - Payment Required

Недостатньо кредитів для виконання цього завдання.

429 - Too Many Requests

Ви перевищили обмеження частоти.

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

GET/openapi/v1/resize/:id

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

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

Параметри

Name
id
Type
path
Description
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
}

DELETE/openapi/v1/resize/: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/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 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/resize

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

Ця кінцева точка дозволяє отримати список завдань зміни розміру.

Параметри

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

Повертає

Повертає список об'єктів The Resize Task Objects з пагінацією.

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

GET/openapi/v1/resize/:id/stream

Потоковий запуск завдання «Змінити розмір»

Ця кінцева точка передає оновлення в реальному часі для завдання зі зміни розміру за допомогою Server-Sent Events (SSE).

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор завдання зі зміни розміру для стрімінгу.

Повертає

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

Для завдань зі статусом PENDING або IN_PROGRESS потік відповіді міститиме лише необхідні поля progress та status.

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
}

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

Об'єкт Resize Task представляє завдання зміни розміру.

Властивості

id · string

Унікальний ідентифікатор завдання.

type · string

Тип завдання. Значення — resize.

model_urls · object

URL для завантаження файлу моделі зі зміненим розміром. При використанні input_task_id вихідний файл завжди має формат GLB. При використанні model_url вхідний файл .glb, .obj, .fbx або .stl зберігає свій формат, а вхідний файл .gltf або Data URI дає на виході GLB.

progress · integer

Прогрес виконання завдання (0-100).

status · string

Статус завдання. Можливі значення: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

preceding_tasks · integer

Кількість попередніх завдань у черзі. Має значення лише коли статус PENDING.

created_at · timestamp

Мітка часу створення завдання, у мілісекундах.

started_at · timestamp

Мітка часу початку виконання завдання, у мілісекундах. 0, якщо завдання ще не розпочато.

finished_at · timestamp

Мітка часу завершення завдання, у мілісекундах. 0, якщо завдання ще не завершено.

task_error · object

Об'єкт помилки, якщо завдання завершилося невдало. Детальніше див. Помилки.

consumed_credits · integer

Кількість кредитів, витрачених на це завдання (1 кредит за завдання зміни розміру). Повертає 0 для завдань зі статусом FAILED.