lowpoly буде вимкнено 30 жовт. 2026 р.. meshy-7 як модель 3D-генерації буде вимкнено 31 груд. 2026 р.; як модель текстурування вона залишається доступною. Перейдіть на іншу модель до цих дат, щоб уникнути помилок у запитах. Усі застарілі функції

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: 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 у веб-застосунку. Щоб знайти завдання, 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).

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.