Конвертировать 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
}

Объект задачи Convert

Объект задачи Convert представляет собой задачу конвертации формата.

Свойства

  • id · string

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

  • type · string

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

  • model_urls · object

Ссылки для скачивания сконвертированных файлов модели. URL-адреса будут только для форматов, указанных в target_formats. Свойства для остальных форматов будут пустыми строками.

  • 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.