Text to Motion API

Генеруйте клипи руху персонажа на основі описів природною мовою. Опишіть дію — "персонаж махає рукою", "зомбі повільно бреде вперед" — і отримайте необроблений клип руху, який можна перенацілити на риговані персонажі у вашому власному конвеєрі або DCC-інструментах.

Результатом є окремий клип руху: він не потребує моделі персонажа і не прив'язаний до неї. Щоб спочатку зробити риг персонажа, див. Rigging API. Щоб застосувати згенерований клип до вашого ригованого персонажа, передайте 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 — вони не відображаються в розділі My Assets веб-застосунку. Використовуйте цю кінцеву точку, щоб знайти задачу, 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, яке потрібно видалити.

Повертає

Повертає 200 OK у разі успіху.

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

// Returns 200 Ok on success.

Об'єкт завдання 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
Progress завдання (0-100).
Name
created_at
Type
timestamp
Description
Мітка часу (у мілісекундах з початку епохи) створення завдання.
Мітка часу представляє кількість мілісекунд, що минули з 1 січня 1970 року UTC, відповідно до стандарту RFC 3339. Наприклад, п'ятниця, 1 вересня 2023 12:00:00 за Гринвічем представлена як 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
  Mode, у якому було згенеровано кліп: 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
}