API від тексту до руху

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

Вихідний файл — це окремий кліп руху: він не вимагає і не прив'язаний до моделі персонажа. Щоб спочатку додати скелет до персонажа, дивіться API скелетування.

POST/openapi/v1/text-to-motion

Створити завдання Text to Motion

Цей endpoint створює нове завдання для генерації рухомого кліпу з текстового 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 key.
Name
402 - Payment Required
Description
Недостатньо кредитів для виконання цього завдання.
Name
403 - Forbidden
Description
Prompt був відзначений на moderation.
Name
429 - Too Many Requests
Description
Ви перевищили своє обмеження частоти.

Запит

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

Відповідь

{
  "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 — вони не відображаються в My Assets веб-застосунку. Використовуйте цю кінцеву точку, щоб знайти завдання, 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

Трансляція Завдання з Тексту в Рух

Ця кінцева точка транслює оновлення в реальному часі для завдання з Тексту в Рух, використовуючи Server-Sent Events (SSE).

Параметри

Name
id
Type
path
Description
Унікальний ідентифікатор завдання з Тексту в Рух для трансляції.

Повертає

Повертає потік Об'єктів Завдання з Тексту в Рух у вигляді Server-Sent Events.

Кожен message event несе повний об'єкт завдання. Поки завдання 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": "Task not found"
}

// Події повідомлень не можуть повний об'єкт завдання на кожному етапі; поля результатів залишаються порожніми поки завдання не буде виконано.
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: { // Приклад потоку елемента завдання, яке успішно завершено, яке відповідає структурі Об'єкта Завдання з Тексту в Рух
  "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
Ідентифікатор завдання 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.

Приклад Об'єкта Завдання Текст-у-Рух

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