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

Конвертуйте 3D-модель в інші формати файлів, із завдання Meshy або з файлу моделі.

POST/openapi/v1/convert

Create a Convert task

Створює завдання Конвертувати. Завдання виконується у фоновому режимі. Про типову тривалість виконання завдання див. Час обробки.

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

Параметри

Name
input_task_id
Type
string
Обов'язковий
Description
Обов'язковий, якщо не надіслано model_url. ID завдання, яке створило 3D-модель, наприклад завдання Текст у 3D, Зображення у 3D, Ремеш, Змінити розмір або Ретекстурування. Завдання має бути створене через API та мати статус SUCCEEDED.

Name
model_url
Type
string
Обов'язковий
Description
Обов'язковий, якщо не надіслано input_task_id. Модель для конвертування у вигляді публічної URL-адреси або data URI. Якщо надіслано обидва параметри, Meshy використовує input_task_id.
Модель має бути файлом GLB, glTF, OBJ, FBX або STL розміром не більше 400 МБ за адресою http чи https, або 100 МБ як data URI. Для data URI використовуйте MIME type application/octet-stream.
Файл понад 100 МБ також повинен відповідати таким правилам:
- Файл GLB, glTF, FBX або OBJ може мати не більше 10 000 000 граней. Meshy рахує грані як трикутники, тож квад рахується як 2, а сітка, намальована кілька разів, рахується один раз на кожну копію.
- Файл FBX повинен бути бінарним FBX версії 7.1 або новішим.
- Файл GLB або glTF не повинен використовувати стиснення Draco.

Name
target_formats
Type
string[]
Обов'язковий
Description
Формати файлів для генерації. Вкажіть принаймні один. Відсутній або порожній список повертає 400.
Доступні значення:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Повертає

Поле result відповіді містить ID нового завдання Конвертувати.

Режими відмов

Name
400 - Bad Request
Description
Запит не може бути виконаний. Повідомлення про помилку вказує, яку проблему виявлено. Наприклад:
- Відсутній параметр: Не надіслано ні model_url, ні input_task_id.
- Відсутній target_formats: target_formats відсутній або не містить жодного формату.
- Недійсне вхідне завдання: input_task_id не є успішним завданням API з файлом моделі.
- Недійсний формат моделі: Файл model_url має непідтримуване розширення.
- Недоступна URL-адреса: Meshy не може завантажити файл model_url.
- Файл моделі надто великий: Файл model_url перевищує 400 МБ за адресою http чи https, або 100 МБ як data URI.
- Забагато граней: Файл model_url перевищує 100 МБ і має більше 10 000 000 граней. Зменшіть кількість граней, потім надішліть файл знову.
- ASCII FBX понад 100 МБ: Файл model_url є ASCII FBX розміром понад 100 МБ. Надішліть його як бінарний FBX або GLB.
- Нечитабельний файл моделі: Файл model_url перевищує 100 МБ, і Meshy не може прочитати його заголовок. Наприклад, це GLB або glTF зі стисненням Draco, або бінарний FBX старіший за версію 7.1.
- Заголовок моделі надто складний: Файл model_url перевищує 100 МБ, і його заголовок має забагато сіток, вузлів або записів для перевірки. Зменшіть кількість об'єктів у файлі, потім надішліть його знову.
Виправте запит, потім надішліть його знову. Див. Помилки.
Name
401 - Unauthorized
Description
API-ключ відсутній або недійсний. Перевірте заголовок Authorization.
Name
402 - Payment Required
Description
Наприклад:
- Недостатньо кредитів: На акаунті недостатньо кредитів для цього завдання, або акаунт досяг ліміту кредитів. Перевірте баланс кредитів, потім повторіть спробу.
- Безкоштовний план: Для створення завдання потрібен платний план. Оновіть свій план у налаштуваннях підписки, потім повторіть спробу.
Name
403 - Forbidden
Description
input_task_id є моделлю барельєфа, яку ця кінцева точка не може конвертувати. Повідомлення: This model type does not support this operation. Надішліть іншу модель.
Name
404 - Not Found
Description
input_task_id не відповідає жодному з ваших завдань. Перевірте ID завдання, потім надішліть запит знову.
Name
429 - Too Many Requests
Description
Ви перевищили обмеження частоти. Зачекайте, потім повторіть спробу. Див. Обмеження частоти.

GET/openapi/v1/convert/:id

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

Повертає завдання Конвертувати за його 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": {
      "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
}

Параметри

Name
id
Type
path
Description
ID завдання з відповіді на створення.

Повертає

Об'єкт завдання Конвертувати.

DELETE/openapi/v1/convert/:id

Видалити задачу Convert

Остаточно видаляє задачу Convert, включно з її моделями та даними. Видалення не можна скасувати.

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

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

Name
id
Type
path
Description
ID задачі для видалення.

Статус задачі

Видалення задачі зі статусом PENDING повертає кредити, витрачені на її створення.

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

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

Повертає

200 OK, коли задачу видалено, або 409 Conflict, коли задача має статус IN_PROGRESS.

GET/openapi/v1/convert

List Convert tasks

Повертає список ваших завдань Convert.

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

Параметри

Name
page_num
Type
integer
за замовчуванням 1
Description
Номер сторінки, яку потрібно повернути, до 255. Більше значення поверне 400.

Name
page_size
Type
integer
за замовчуванням 10
Description
Кількість завдань на сторінці, до 100.

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

Повертає

Розбитий на сторінки список об'єктів завдань Convert.

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

Стрімінг задачі конвертації

Передає оновлення задачі конвертації у вигляді Server-Sent Events (SSE).

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
}

Параметри

Name
id
Type
path
Description
ID задачі з відповіді на створення.

Повертає

Потік об'єктів задачі конвертації у вигляді Server-Sent Events.

Кожна подія містить повний об'єкт задачі, у тому ж форматі, що й повертає кінцева точка Get. Поки задача має статус PENDING або IN_PROGRESS, її поля результату ще не мають значень.

Об'єкт завдання Convert

Об'єкт завдання Convert описує одне перетворення формату 3D-моделі. Він містить статус, progress і файли моделі, коли завдання завершується успішно.

Властивості

Name
id
Type
string
Description
ID завдання. Розглядайте його як непрозорий рядок і не покладайтеся на його формат.
Name
type
Type
string
Description
Тип завдання, завжди convert.
Name
model_urls
Type
object
Description
URL-адреси для завантаження конвертованої моделі, по одній на кожен формат файлу. URL-адреси мають лише формати з target_formats. Формат, який ви не запитували, не має ключа, на відміну від порожнього рядка.
Name
progress
Type
integer
Description
Наскільки завдання виконано, у відсотках. Дорівнює 0, доки завдання не почнеться, і 100, коли воно завершується успішно.
Name
status
Type
string
Description
Статус завдання, один з PENDING, IN_PROGRESS, SUCCEEDED, FAILED або CANCELED.
Name
preceding_tasks
Type
integer
Description
Кількість завдань попереду цього в черзі. Значення має сенс лише, доки завдання перебуває у статусі PENDING.
Name
created_at
Type
timestamp
Description
Час створення завдання, у мілісекундах Unix.
Name
started_at
Type
timestamp
Description
Час початку завдання, у мілісекундах Unix. Дорівнює 0, доки завдання не почнеться.
Name
finished_at
Type
timestamp
Description
Час завершення завдання, у мілісекундах Unix. Дорівнює 0, доки завдання не завершиться.
Name
expires_at
Type
timestamp
Description
Час, коли URL-адреси для завантаження завдання закінчуються, у мілісекундах Unix. Дорівнює 0, доки завдання не завершиться.
Name
texture_urls
Type
array
Description
URL-адреси для завантаження текстурних карт моделі, коли завдання завершується успішно: масив об'єктів, по одному на кожен набір текстур. Кожен об'єкт має URL base_color, а також може мати URL metallic, roughness, normal, emission та metallic_roughness. Дорівнює null, доки завдання не завершиться успішно, і порожньому масиву, коли модель не має текстурних карт.
Name
task_error
Type
object
Description
Деталі помилки, коли завдання завершується невдало. Див. Помилки.
Name
consumed_credits
Type
integer
Description
Кількість кредитів, використаних завданням, що дорівнює 1 для завдання Convert. Дорівнює 0 для завдання зі статусом FAILED.