Конвертувати API

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

POST/openapi/v1/convert

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

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

Параметри

Обов'язковим є лише один з параметрів 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-ключ.

402 - Payment Required

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

429 - Too Many Requests

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

Request

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

Response

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

GET/openapi/v1/convert/:id

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

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

Параметри

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

Повертає

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

Request

GET

/openapi/v1/convert/:id

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

Response

{
  "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
ID завдання конвертації, яке потрібно видалити.

Статус завдання

Завдання, яке ще перебуває у статусі PENDING, видаляється, а кредити, витрачені під час створення, повертаються.

Завдання, яке вже перебуває у статусі IN_PROGRESS, видалити не можна: запит відхиляється з 409 Conflict, а завдання продовжує виконуватися. Кредити за завдання, яке воркер уже почав виконувати, не підлягають поверненню, тому видалення його посеред виконання коштувало б вам і кредитів, і результату. Дочекайтеся, поки воно досягне статусу SUCCEEDED, FAILED або CANCELED, а потім видаліть його.

Завдання у кінцевому статусі (SUCCEEDED, FAILED або CANCELED) видаляється без повернення коштів.

Повертає

Повертає 200 OK у разі успіху, або 409 Conflict, якщо завдання перебуває у статусі IN_PROGRESS.

Request

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

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/convert

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

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

Параметри

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/convert

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

Response

[
  {
    "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.

Request

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

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

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.