Text to Motion API

Generujte pohybové klipy postav z popisů v přirozeném jazyce. Popište akci — „postava mává“, „zombie se belhá vpřed“ — a získáte surový pohybový klip, který můžete přeretargetovat na postavy s kostrou ve svém vlastním pipeline nebo DCC nástrojích.

Výstupem je samostatný pohybový klip: nevyžaduje model postavy a není k žádnému připojen. Chcete-li nejprve provést rigging postavy, podívejte se na Rigging API. Chcete-li aplikovat vygenerovaný klip na svou postavu s riggem, předejte id úlohy jako motion_task_id do Animation API — aplikujte jej v rámci 3denního okna pro uchování assetů.

POST/openapi/v1/text-to-motion

Vytvoření úlohy Text to Motion

Tento koncový bod vytvoří novou úlohu pro generování pohybové sekvence z textového promptu.

Úloha s mode prime stojí 10 kreditů a generuje výsledek pomocí našeho nejkvalitnějšího modelu pro pohyb. Úloha s mode swift stojí 3 kredity a generuje výsledek rychleji pomocí našeho ekonomického modelu pro pohyb.

Parametry

Name
prompt
Type
string
Povinné
Description
Popis pohybu, který se má vygenerovat, v přirozeném jazyce. Maximálně 400 znaků.
Name
mode
Type
string
výchozí prime
Description
Mode generování pohybu. Dostupné hodnoty: prime, swift. prime vytváří nejvyšší kvalitu a výstupem je FBX; swift je rychlejší a levnější a výstupem je BVH.
Name
duration
Type
number
Povinné
Description
Cílová délka pohybové sekvence v sekundách. Mezi 2 a 10, v krocích po 0.5 (například 2, 2.5, 3, … 10).

Návratová hodnota

Vlastnost result v odpovědi obsahuje id úlohy nově vytvořené úlohy Text to Motion.

Způsoby selhání

Name
400 - Bad Request
Description
Požadavek byl nepřijatelný. Běžné příčiny:
- Chybějící nebo prázdný prompt: prompt chybí, je prázdný nebo delší než 400 znaků.
- Neplatný mode: mode není prime ani swift.
- Neplatná duration: duration chybí, je mimo rozsah 2–10, nebo neodpovídá kroku 0.5 sekundy.
Name
401 - Unauthorized
Description
Autentizace se nezdařila. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatek kreditů k provedení této úlohy.
Name
403 - Forbidden
Description
Prompt byl označen moderací obsahu.
Name
429 - Too Many Requests
Description
Překročili jste svůj limit rychlosti.

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

Načtení úlohy Text to Motion

Tento koncový bod umožňuje načíst úlohu Text to Motion na základě platného id úlohy. Podrobnosti o tom, které vlastnosti jsou zahrnuty, najdete v části Objekt úlohy Text to Motion.

Parametry

Name
id
Type
path
Description
Unikátní identifikátor úlohy Text to Motion, kterou chcete načíst.

Návratová hodnota

Odpověď obsahuje objekt úlohy Text to Motion. Podrobnosti najdete v části Objekt úlohy 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

Výpis úloh Text to Motion

Vrátí stránkovaný seznam úloh Text to Motion volajícího, seřazený od nejnovějších. Standardní stránkování pomocí page_num a page_size.

Odpověď je pole objektů úlohy Text to Motion.

Upozorňujeme, že úlohy vytvořené přes API jsou spravovány prostřednictvím API — v sekci Moje assety ve webové aplikaci se nezobrazují. Tento koncový bod použijte k nalezení úlohy, jejíž ID již nemáte.

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

Streamování úlohy Text to Motion

Tento koncový bod streamuje aktualizace v reálném čase pro úlohu Text to Motion pomocí Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Jedinečný identifikátor úlohy Text to Motion, kterou chcete streamovat.

Návratová hodnota

Vrací proud objektů úlohy Text to Motion jako Server-Sent Events.

Každá událost message obsahuje celý objekt úlohy. Dokud je úloha ve stavu PENDING nebo IN_PROGRESS, pole result jsou stále prázdná ("" / 0) a finished_at / expires_at mají hodnotu 0; sledujte status a 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

Smazání úlohy Text to Motion

Tento koncový bod trvale smaže úlohu Text to Motion, včetně vygenerovaného pohybového klipu. Tuto akci nelze vrátit zpět.

Parametry cesty

Name
id
Type
path
Description
ID úlohy Text to Motion, kterou chcete smazat.

Návratová hodnota

V případě úspěchu vrací 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.

Objekt úkolu Text to Motion

Objekt úkolu Text to Motion představuje pracovní jednotku pro generování pohybové animace z textového promptu.

Vlastnosti

Name
id
Type
string
Description
Jedinečný identifikátor úkolu.
Name
type
Type
string
Description
Typ úkolu. Hodnota je text-to-motion.
Name
status
Type
string
Description
Stav úkolu. Možné hodnoty: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress úkolu (0–100).
Name
created_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy) vytvoření úkolu.
Časové razítko představuje počet milisekund uplynulých od 1. ledna 1970 UTC podle standardu RFC 3339. Například pátek 1. září 2023 12:00:00 GMT je vyjádřen jako 1693569600000. To platí pro všechna časová razítka v Meshy API.
Name
started_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy) zahájení zpracování úkolu. 0, pokud zpracování nebylo zahájeno.
Name
finished_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy) dokončení úkolu. 0, pokud nebyl dokončen.
Name
expires_at
Type
timestamp
Description
Časové razítko (v milisekundách od epochy) vypršení platnosti výsledných assetů úkolu. 0, dokud úkol neskončí. Vygenerovaný klip je uchováván po dobu 3 dnů od dokončení úkolu; stáhněte si jej před vypršením platnosti.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úkolů v pořadí čekání. Má smysl pouze pokud je stav PENDING; vynecháno, pokud je nulové.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných tímto úkolem. 10 pro mode prime, 3 pro mode swift. U úkolů se stavem FAILED vrací 0 (kredity jsou při selhání vráceny).
Name
task_error
Type
object
Description
Podrobnosti o chybě u neúspěšných úkolů; null, pokud úkol nemá stav FAILED. Úplnou referenci objektu task_error najdete v části Chyby.
Name
result
Type
object
Description
Obsahuje vygenerovanou pohybovou animaci po dokončení úkolu se stavem SUCCEEDED; do té doby jsou pole přítomna, ale prázdná ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL ke stažení vygenerovaného pohybového klipu. URL je znovu podepsáno při každém čtení a jeho platnost vyprší s dobou uchování úkolu.
- Name
  motion_format
  Type
  string
  Description
  Formát souboru klipu: fbx pro mode prime, bvh pro mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Délka vygenerovaného klipu v milisekundách.
- Name
  mode
  Type
  string
  Description
  Mode, se kterým byl klip vygenerován: prime nebo 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
}