Resize API

API Resize позволяет изменить размер существующих 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 МБ для URI data:.
Файл GLB, glTF, FBX или OBJ размером более 100 МБ может содержать не более 10 000 000 граней. Грани считаются как треугольники: четырёхугольник считается за 2, а сетка, отрисованная несколько раз, считается один раз за каждую копию. При размере более 100 МБ файл FBX должен быть бинарным FBX версии 7.1 или новее, а файл GLB или glTF не должен использовать сжатие Draco.

Требуется указать ровно один mode изменения размера: 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.
Отсутствует mode изменения размера: необходимо указать хотя бы один из параметров 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 МБ (URI data:).
Слишком много граней: файл по 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

List Resize Tasks

Этот эндпоинт позволяет получить список задач изменения размера.

Параметры

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

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

Properties

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

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 кредит за задачу изменения размера). Для задач со статусом FAILED возвращается 0.