Text to Motion API

Создавайте клипы движений персонажей из описаний на естественном языке. Опишите действие — "персонаж машет рукой", "зомби идет вперед" — и получите сырой клип движения, который вы можете перенаправить на привязанных персонажей в вашем собственном пайплайне или инструментах DCC.

Выходные данные — это автономный клип движения: он не требует и не привязан к модели персонажа. Чтобы сначала добавить скелет к персонажу, обратитесь к Rigging API.

POST/openapi/v1/text-to-motion

Создать задачу перевода текста в движение

Этот эндпоинт создает новую задачу для генерации клипа движения из текстового prompt.

Задача с mode prime стоит 10 кредитов и генерирует с использованием нашей наиболее качественной модели движения. Задача с mode swift стоит 3 кредита и генерирует быстрее с использованием нашей экономичной модели движения.

Параметры

Name
prompt
Type
string
Обязательный
Description
Описание движения на естественном языке. Максимум 400 символов.
Name
mode
Type
string
по умолчанию prime
Description
Режим генерации движения. Доступные значения: prime, swift. prime производит наивысшее качество и выводит FBX; swift быстрее и дешевле и выводит BVH.
Name
duration
Type
number
Обязательный
Description
Целевая длительность клипа движения в секундах. Между 2 и 10, с шагом 0.5 (например 2, 2.5, 3, … 10).

Возвращаемые значения

Свойство result ответа содержит id задачи новосозданной задачи перевода текста в движение.

Ошибки

Name
400 - Bad Request
Description
Запрос был неприемлемым. Общие причины:
- Отсутствующий или пустой prompt: prompt отсутствует, пустой или длиннее 400 символов.
- Недопустимый режим: mode не является prime или swift.
- Недопустимая длительность: duration отсутствует, вне диапазона 2–10, или не соответствует шагу 0.5 секунды.
Name
401 - Unauthorized
Description
Аутентификация не удалась. Пожалуйста, проверьте ваш API-ключ.
Name
402 - Payment Required
Description
Недостаточно кредитов для выполнения этой задачи.
Name
403 - Forbidden
Description
Prompt был отмечен системой moderation.
Name
429 - Too Many Requests
Description
Вы превысили ваше ограничение частоты.

Request

POST

/openapi/v1/text-to-motion

# Генерация клипа движения только с обязательными параметрами
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "duration": 3
  }'

# Генерация быстрого, экономичного клипа в режиме Swift
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "mode": "swift",
    "duration": 4.5
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

GET/openapi/v1/text-to-motion/:id

Получение задачи "Text to Motion"

Этот эндпоинт позволяет получить задачу "Text to Motion" по заданному действительному идентификатору задачи id. Обратитесь к разделу Объект задачи "Text to Motion", чтобы увидеть, какие свойства включены.

Параметры

Name
id
Type
path
Description
Уникальный идентификатор задачи "Text to Motion", которую нужно получить.

Возвращает

Ответ содержит объект задачи "Text to Motion". Проверьте раздел Объект задачи "Text to Motion" для подробностей.

Запрос

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Ответ

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

GET/openapi/v1/text-to-motion

Список задач "Текст в движение"

Возвращает список задач "Текст в движение" вызывающего абонента с пагинацией, начиная с самых новых. Стандартная пагинация через page_num и page_size.

Ответ - это массив из объектов задачи "Текст в движение".

Обратите внимание, что задачи, созданные через API, управляются через API — они не отображаются в разделе Мои Активы веб-приложения. Используйте этот эндпоинт, чтобы найти задачу, ID которой у вас больше нет.

Запрос

GET

/openapi/v1/text-to-motion

curl "https://api.meshy.ai/openapi/v1/text-to-motion?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Ответ

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

GET/openapi/v1/text-to-motion/:id/stream

Передача задачи Text to Motion

Этот эндпоинт передает обновления в реальном времени для задачи Text to Motion с использованием Server-Sent Events (SSE).

Параметры

Name
id
Type
path
Description
Уникальный идентификатор задачи Text to Motion для передачи.

Возвращает

Возвращает поток Объектов задачи Text to Motion как Server-Sent Events.

Каждое событие message содержит полный объект задачи. Пока задача находится в состоянии PENDING или IN_PROGRESS, поля result остаются пустыми ("" / 0), а finished_at / expires_at равны 0; следите за status и progress.

Запрос

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Поток ответа

// Пример события ошибки
event: error
data: {
  "status_code": 404,
  "message": "Задача не найдена"
}

// События сообщений содержат полный объект задачи на каждом этапе; поля
// результата остаются пустыми до тех пор, пока задача не будет выполнена.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "IN_PROGRESS",
  "progress": 50,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 0,
  "expires_at": 0,
  "task_error": null,
  "result": {
    "motion_url": "",
    "motion_format": "",
    "duration_ms": 0,
    "mode": ""
  },
  "consumed_credits": 10
}

event: message
data: { // Пример элемента потока выполненной задачи, отражающий структуру объекта задачи Text to Motion
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

DELETE/openapi/v1/text-to-motion/:id

Удаление задачи Text to Motion

Этот эндпоинт навсегда удаляет задачу Text to Motion, включая сгенерированный видеоклип. Это действие необратимо.

Параметры пути

Name
id
Type
path
Description
ID задачи Text to Motion для удаления.

Возврат

Возвращает 200 OK в случае успеха.

Запрос

DELETE

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Ответ

// Возвращает 200 Ok в случае успеха.

Объект задачи "Текст в движение"

Объект задачи "Текст в движение" представляет собой рабочую единицу для создания клипа движения из текстового prompt.

Свойства

Name
id
Type
string
Description
Уникальный идентификатор задачи.
Name
type
Type
string
Description
Тип задачи. Значение: text-to-motion.
Name
status
Type
string
Description
Статус задачи. Возможные значения: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Прогресс задачи (0-100).
Name
created_at
Type
timestamp
Description
Временная метка (в миллисекундах с начала эпохи), когда задача была создана.
Временная метка представляет количество миллисекунд, прошедших с 1 января 1970 года по UTC, в соответствии со стандартом RFC 3339. Например, пятница, 1 сентября 2023 года, 12:00:00 PM GMT представляется как 1693569600000. Это относится ко всем временным меткам в Meshy API.
Name
started_at
Type
timestamp
Description
Временная метка (в миллисекундах с начала эпохи), когда задача начала выполняться. 0 если не начата.
Name
finished_at
Type
timestamp
Description
Временная метка (в миллисекундах с начала эпохи), когда задача была завершена. 0 если не завершена.
Name
expires_at
Type
timestamp
Description
Временная метка (в миллисекундах с начала эпохи), когда активы результата задачи станут недействительными. 0 до окончания задачи. Созданный клип сохраняется в течение 3 дней после завершения задачи; загрузите его до истечения срока действия.
Name
preceding_tasks
Type
integer
Description
Количество предшествующих задач в очереди. Имеет смысл только если статус PENDING; опускается, когда значение равно нулю.
Name
consumed_credits
Type
integer
Description
Количество кредитов, потребленных этой задачей. 10 для режима prime, 3 для режима swift. Возвращает 0 для задач с статусом FAILED (кредиты возвращаются при неудаче).
Name
task_error
Type
object
Description
Подробности ошибки для неудачных задач; null, если задача не FAILED. См. Ошибки для полной справки по объекту task_error.
Name
result
Type
object
Description
Содержит сгенерированный клип движения, когда задача SUCCEEDED; до тех пор поля присутствуют, но пусты ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Скачиваемая URL-адрес для сгенерированного клипа движения. URL подписывается заново при каждом чтении и истекает одновременно с окном сохранения задачи.
- Name
  motion_format
  Type
  string
  Description
  Формат файла клипа: fbx для режима prime, bvh для режима swift.
- Name
  duration_ms
  Type
  integer
  Description
  Продолжительность сгенерированного клипа в миллисекундах.
- Name
  mode
  Type
  string
  Description
  Режим, в котором клип был сгенерирован: prime или swift.

Example Text to Motion Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}