API Конвертації

API Конвертації дозволяє конвертувати існуючі 3D моделі в різні формати файлів.

POST/openapi/v1/convert

Створити Завдання Конвертації

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

Параметри

Тільки один з input_task_id або model_url є обов'язковим. Якщо обидва надані, input_task_id має пріоритет.

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

Name
model_url
Type
string
Обов'язковий
Description
Публічно доступний URL або Data URI, що вказує на файл 3D моделі. Підтримувані формати: .glb, .gltf, .obj, .fbx, .stl. Для Data URI використовуйте MIME type: application/octet-stream.

Name
target_formats
Type
string[]
Обов'язковий
Description
Список вихідних форматів для конвертованої моделі. Доступні значення: glb, fbx, obj, usdz, blend, stl, 3mf.

Повертає

Властивість result відповіді містить id новоствореного завдання конвертації.

Режими Помилок

400 - Bad Request

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

Відсутній параметр: Або model_url, або input_task_id повинні бути надані.
Відсутні target_formats: Повинен бути вказаний принаймні один цільовий формат.
Неправильне вхідне завдання: input_task_id повинен посилатися на успішне завдання.
Неправильний формат моделі: model_url вказує на файл з непідтримуваним розширенням.
Недоступний URL: model_url не може бути завантажений.

401 - Unauthorized

Автентифікація не вдалася. Будь ласка, перевірте ваш API key.

402 - Payment Required

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

429 - Too Many Requests

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

Запит

POST

/openapi/v1/convert

curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Відповідь

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

GET/openapi/v1/convert/:id

Отримання завдання на конвертацію

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

Параметри

Name
id
Type
path
Description
ID завдання на конвертацію, яке потрібно отримати.

Повертає

Об'єкт завдання на конвертацію.

Запит

GET

/openapi/v1/convert/:id

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

Відповідь

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

DELETE/openapi/v1/convert/:id

Видалити завдання Конвертувати

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

Параметри шляху

Name
id
Type
path
Description
Ідентифікатор завдання конвертувати, яке потрібно видалити.

Повертає

Повертає 200 OK у разі успіху.

Запит

DELETE

/openapi/v1/convert/:id

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

Відповідь

// Returns 200 Ok on success.

GET/openapi/v1/convert

Список Завдань Конвертації

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

Параметри

Name
page_num
Type
integer
за замовчуванням 1
Description
Номер сторінки для пагінації.

Name
page_size
Type
integer
за замовчуванням 10
Description
Обмеження розміру сторінки. Максимально дозволено 50 елементів.

Name
sort_by
Type
string
Description
Поле для сортування. Доступні значення:
- +created_at: Сортувати за часом створення у зростаючому порядку.
- -created_at: Сортувати за часом створення у спадному порядку.

Повертає

Повертає список з пагінацією Об'єктів Завдань Конвертації.

Запит

GET

/openapi/v1/convert

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

Відповідь

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

GET/openapi/v1/convert/:id/stream

Потокове передавання завдання Конвертації

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

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор для завдання конвертації, яке потрібно передавати.

Повертає

Повертає потік Об'єктів Завдання Конвертації як Server-Sent Events.

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

Запит

GET

/openapi/v1/convert/:id/stream

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

Потік Відповіді

// 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": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Об'єкт Завдання Конвертації

Об'єкт Завдання Конвертації представляє завдання з конвертації формату.

Властивості

id · string

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

type · string

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

model_urls · object

Завантажувані URL-адреси для конвертованих файлів моделі. Тільки формати, вказані в target_formats, матимуть 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.