Text to Motion API

Generujte pohybové klipy postav z textových popisů. Popište akci, například „postava mává“ nebo „zombie se belhá dopředu“, a získáte surový pohybový klip. Tento klip můžete přenést (retarget) na rigované postavy ve vlastním pipeline nebo DCC nástrojích.

Výstupem je samostatný pohybový klip. Nepotřebuje model postavy a není k žádnému připojen. Pokud chcete postavu nejprve rigovat, podívejte se na Rigging API. Chcete-li klip aplikovat na vaši rigovanou postavu, odešlete id úlohy jako motion_task_id do Animation API.

POST/openapi/v1/text-to-motion

Vytvoření úlohy Text to Motion

Vytvoří úlohu Text to Motion, která vygeneruje pohybovou sekvenci (motion clip) z textového promptu.

Úloha běží na pozadí. Informace o tom, jak dlouho úloha obvykle trvá, najdete v části Doby zpracování.

Úloha v mode prime stojí 10 kreditů a využívá kvalitnější pohybový model Meshy. Úloha v mode swift stojí 3 kredity a využívá rychlejší, levnější pohybový model.

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

Parametry

Name
prompt
Type
string
Povinné
Description
Text popisující pohyb, který se má vygenerovat, až 400 znaků. Delší text vrátí 400.
Name
mode
Type
string
výchozí prime
Description
Pohybový model, který zároveň určuje formát souboru sekvence.
Dostupné hodnoty:
- prime: vyšší kvalita, vrací klip ve formátu FBX
- swift: rychlejší a levnější, vrací klip ve formátu BVH
Jakákoli jiná hodnota vrátí 400.
Name
duration
Type
number
Povinné
Description
Cílová délka klipu v sekundách, od 2 do 10 v krocích po 0.5, například 2, 2.5 nebo 3. Jakákoli jiná hodnota vrátí 400.

Návratové hodnoty

Pole result v odpovědi obsahuje ID nové úlohy Text to Motion.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek nelze spustit. Chybová zpráva uvádí, jaký problém byl zjištěn. Například:
- 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 až 10, nebo neodpovídá kroku 0.5 sekundy.
Opravte požadavek a odešlete jej znovu. Viz Chyby.
Name
401 - Unauthorized
Description
API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.
Name
402 - Payment Required
Description
Například:
- Nedostatek kreditů: Účet nemá dostatek kreditů pro tuto úlohu, nebo účet dosáhl limitu kreditů. Zkontrolujte svůj zůstatek kreditů a zkuste to znovu.
- Bezplatný plán: Vytvoření úlohy vyžaduje placený plán. Upgradujte svůj plán v nastavení předplatného a zkuste to znovu.
Name
403 - Forbidden
Description
Moderation obsahu označila prompt jako problematický. Změňte prompt a odešlete požadavek znovu.
Name
429 - Too Many Requests
Description
Překročili jste limit rychlosti. Počkejte a zkuste to znovu. Viz Limity rychlosti.

GET/openapi/v1/text-to-motion/:id

Získání úlohy Text to Motion

Vrátí úlohu Text to Motion podle jejího 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
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Objekt úlohy Text to Motion.

GET/openapi/v1/text-to-motion

Seznam úloh Text to Motion

Vrátí stránkovaný seznam vašich úloh Text to Motion, seřazený od nejnovějších. Pro procházení seznamu po stránkách použijte page_num a page_size.

Odpovědí je pole objektů úloh Text to Motion.

Úlohy, které vytvoříte přes API, zůstávají v API a nezobrazují se v sekci My Assets ve webové aplikaci. Pokud potřebujete najít úlohu, jejíž ID již nemáte, použijte tento koncový bod.

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

Streamuje aktualizace úlohy Text to Motion jako 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
}

Parametry

Name
id
Type
path
Description
ID úlohy z odpovědi na vytvoření.

Návratová hodnota

Proud objektů úlohy Text to Motion jako Server-Sent Events.

Každá událost message nese kompletní objekt úlohy. Dokud je úloha ve stavu PENDING nebo IN_PROGRESS, pole result jsou prázdná ("" nebo 0) a finished_at a expires_at jsou 0. Pro sledování průběhu úlohy sledujte status a progress.

DELETE/openapi/v1/text-to-motion/:id

Smazání úlohy Text to Motion

Trvale smaže úlohu Text to Motion, včetně jejího pohybového klipu. Smazání nelze vrátit zpět.

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

Parametry cesty

Name
id
Type
path
Description
ID úlohy, která se má smazat.

Stav úlohy

Smazání úlohy ve stavu PENDING vrátí kredity, které byly použity při jejím vytvoření.

Úlohu ve stavu IN_PROGRESS nelze smazat. Požadavek vrátí 409 Conflict a úloha dál běží. Meshy nevrací kredity za úlohu, která už byla spuštěna, takže jejím smazáním byste přišli jak o kredity, tak o výsledek. Počkejte, až dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

Smazání úlohy v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) nevrací kredity.

Návratová hodnota

200 OK, když je úloha smazána, nebo 409 Conflict, když je úloha ve stavu IN_PROGRESS.

Objekt úlohy Text to Motion

Objekt úlohy Text to Motion popisuje generování jednoho pohybového klipu. Obsahuje stav, progress a klip, jakmile je úloha úspěšná.

Vlastnosti

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 úlohy. Považujte ho za neprůhledný řetězec a nespoléhejte na jeho formát.
Name
type
Type
string
Description
Typ úlohy, vždy text-to-motion.
Name
status
Type
string
Description
Stav úlohy, jeden z PENDING, IN_PROGRESS, SUCCEEDED, FAILED nebo CANCELED.
Name
progress
Type
integer
Description
Jak velká část úlohy je hotová, jako procento od 0 do 100.
Name
created_at
Type
timestamp
Description
Čas vytvoření úlohy, v milisekundách Unixu.
Name
started_at
Type
timestamp
Description
Čas zahájení úlohy, v milisekundách Unixu. Je 0, dokud úloha nezačne.
Name
finished_at
Type
timestamp
Description
Čas dokončení úlohy, v milisekundách Unixu. Je 0, dokud úloha neskončí.
Name
expires_at
Type
timestamp
Description
Čas, kdy vyprší platnost výsledných souborů úlohy, v milisekundách Unixu. Je 0, dokud úloha neskončí. Meshy uchovává klip po dobu 3 dnů od dokončení úlohy, takže si ho do té doby stáhněte.
Name
preceding_tasks
Type
integer
Description
Počet úloh před touto úlohou ve frontě. Hodnota má smysl pouze tehdy, když je úloha ve stavu PENDING. Pole se vynechává, pokud je hodnota 0.
Name
consumed_credits
Type
integer
Description
Počet kreditů, které úloha spotřebovala, 10 pro mode prime nebo 3 pro mode swift. U úlohy se stavem FAILED je to 0, protože Meshy při selhání úlohy kredity vrací.
Name
task_error
Type
object
Description
Podrobnosti o chybě, pokud úloha selže, jinak null. Viz Chyby.
Name
result
Type
object
Description
Vygenerovaný pohybový klip, jakmile je úloha úspěšná. Do té doby jsou pole přítomna, ale prázdná ("" nebo 0).
- Name
  motion_url
  Type
  string
  Description
  URL ke stažení pohybového klipu. Meshy podepisuje URL znovu při každém čtení a jeho platnost vyprší s koncem retenčního okna úlohy.
- Name
  motion_format
  Type
  string
  Description
  Formát souboru klipu, fbx pro mode prime nebo bvh pro mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Délka klipu, v milisekundách.
- Name
  mode
  Type
  string
  Description
  Mode, který Meshy použilo ke generování klipu, prime nebo swift.