Text to Motion API

Создавайте клипы движений персонажей на основе описаний на естественном языке. Опишите действие — «персонаж машет рукой», «зомби бредёт вперёд» — и получите необработанный клип движения, который можно перенацелить на персонажей с骨骼绑定(rig) в вашем собственном пайплайне или DCC-инструментах.

Результатом является самостоятельный клип движения: он не требует и не привязан к модели персонажа. Чтобы сначала выполнить骨骼绑定(rigging) персонажа, см. Rigging API. Чтобы применить сгенерированный клип к персонажу с骨骼绑定(rig), передайте id задачи как motion_task_id в Animation API — примените его в течение 3-дневного окна хранения ресурсов.

POST/openapi/v1/text-to-motion

Создать задачу 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 задачи вновь созданной задачи Text to Motion.

Режимы сбоя

Name
400 - Bad Request
Description
Запрос был неприемлем. Распространённые причины:
- Отсутствующий или пустой prompt: prompt отсутствует, пуст или длиннее 400 символов.
- Некорректный mode: mode не равен prime или swift.
- Некорректная duration: 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

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

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.

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
}

GET/openapi/v1/text-to-motion

Список задач Text to Motion

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

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

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

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

Параметры

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.

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 stream item, mirroring The Text to Motion Task Object structure
  "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, которую нужно удалить.

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

Задача, которая всё ещё находится в статусе PENDING, удаляется, а кредиты, списанные при её создании, возвращаются.

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

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

Возвращает

Возвращает 200 OK при успехе или 409 Conflict, если задача находится в статусе IN_PROGRESS.

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

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

Объект задачи Text to Motion представляет собой единицу работы по генерации клипа движения из текстового 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 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 перезаверяется при каждом обращении и истекает вместе с окном хранения задачи.
- 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
}