Text to Motion API

Создавайте клипы с движениями персонажа на основе текстовых описаний. Опишите действие, например «персонаж машет рукой» или «зомби бредёт вперёд», и получите готовый клип с движением. Вы можете перенацелить клип на риггированных персонажей в вашем собственном пайплайне или DCC-инструментах.

Результатом является самостоятельный клип с движением. Он не требует модели персонажа и не привязан к ней. Чтобы сначала выполнить риггинг персонажа, см. Rigging API. Чтобы применить клип к вашему риггированному персонажу, отправьте id задачи в качестве motion_task_id в Animation API.

POST/openapi/v1/text-to-motion

Создание задачи Text to Motion

Создаёт задачу Text to Motion, которая генерирует анимационный клип на основе текстового prompt.

Задача выполняется в фоновом режиме. Информацию о том, сколько обычно занимает выполнение задачи, см. в разделе Время обработки.

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

Request

POST

/openapi/v1/text-to-motion

# Generate a motion clip with required params only
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
  }'

# Generate a fast, economical clip with Swift mode
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"
}

Параметры

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

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

Поле result в ответе содержит ID новой задачи Text to Motion.

Режимы сбоев

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

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

Получить задачу Text to Motion

Возвращает задачу Text to Motion по её ID.

Request

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

Response

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

Параметры

Name
id
Type
path
Description
ID задачи из ответа на создание.

Возвращает

Объект задачи Text to Motion.

GET/openapi/v1/text-to-motion

Получение списка задач Text to Motion

Возвращает постраничный список ваших задач Text to Motion, сначала самые новые. Для постраничного просмотра списка используйте page_num и page_size.

Ответ представляет собой массив объектов задачи Text to Motion.

Задачи, созданные через API, остаются в API и не отображаются в разделе My Assets в веб-приложении. Чтобы найти задачу, идентификатор которой у вас больше не сохранён, используйте этот эндпоинт.

Request

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

Response

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

Request

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

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message events carry the full task object at every stage; the result
// fields stay empty until the task succeeds.
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: { // Example of a SUCCEEDED task event, with the same fields as the 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
}

Параметры

Name
id
Type
path
Description
ID задачи из ответа на создание.

Возвращает

Поток объектов задачи Text to Motion в виде событий Server-Sent Events.

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

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

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

Безвозвратно удаляет задачу Text to Motion, включая её клип движения. Отменить удаление нельзя.

Request

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

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.

Объект задачи Text to Motion

Объект задачи Text to Motion описывает генерацию одного клипа движения. Он содержит статус, progress и сам клип, когда задача выполнена успешно.

Свойства

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
}

Name
id
Type
string
Description
ID задачи. Рассматривайте его как непрозрачную строку и не полагайтесь на её формат.
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
Время создания задачи, в миллисекундах Unix.
Name
started_at
Type
timestamp
Description
Время начала задачи, в миллисекундах Unix. Равно 0, пока задача не начнётся.
Name
finished_at
Type
timestamp
Description
Время завершения задачи, в миллисекундах Unix. Равно 0, пока задача не завершится.
Name
expires_at
Type
timestamp
Description
Время, когда истекает срок действия файлов результата задачи, в миллисекундах Unix. Равно 0, пока задача не завершится. Meshy хранит клип в течение 3 дней после завершения задачи, поэтому скачайте его до истечения этого срока.
Name
preceding_tasks
Type
integer
Description
Количество задач перед данной в очереди. Значение имеет смысл только пока задача находится в статусе PENDING. Поле отсутствует, если значение равно 0.
Name
consumed_credits
Type
integer
Description
Количество кредитов, использованных задачей: 10 для режима prime или 3 для режима swift. Равно 0 для задачи со статусом FAILED, потому что Meshy возвращает кредиты при неудачном выполнении задачи.
Name
task_error
Type
object
Description
Подробности ошибки, если задача завершилась неудачно, и null в противном случае. См. Ошибки.
Name
result
Type
object
Description
Сгенерированный клип движения, когда задача выполнена успешно. До этого момента поля присутствуют, но пусты ("" или 0).
- Name
  motion_url
  Type
  string
  Description
  URL для скачивания клипа движения. Meshy подписывает URL заново при каждом чтении, и его срок действия истекает вместе с окном хранения задачи.
- Name
  motion_format
  Type
  string
  Description
  Формат файла клипа, fbx для режима prime или bvh для режима swift.
- Name
  duration_ms
  Type
  integer
  Description
  Длительность клипа, в миллисекундах.
- Name
  mode
  Type
  string
  Description
  Режим, который Meshy использовал для генерации клипа, prime или swift.