Resize 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, сервис использует ИИ-зрение для автоматической оценки реальной высоты объекта и соответствующего изменения размера модели. Начало координат по умолчанию будет 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 задачи изменения размера, которую нужно получить.

Возвращает

Объект задачи изменения размера (Resize Task).

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 Task представляет собой задачу изменения размера.

Свойства

id · string

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

type · string

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

model_urls · object

Скачиваемый URL для файла модели с измененным размером. При использовании input_task_id результат всегда в формате GLB. При использовании model_url результат сохраняет исходный формат.

progress · integer

Progress задачи (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.