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. Вихідний формат збереже початковий формат вхідної моделі.

Потрібен рівно один режим зміни розміру: 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-зір, щоб автоматично оцінити реальну висоту об'єкта та відповідно змінити розмір моделі. Початок координат за замовчуванням буде 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.

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

Повертає

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

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

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

Властивості

id · string

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

type · string

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

model_urls · object

URL для завантаження файлу моделі зі зміненим розміром. При використанні input_task_id вихідний формат завжди GLB. При використанні model_url вихідний формат зберігає оригінальний.

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.