Text to Motion API

Generujte pohybové klipy postav z popisů v přirozeném jazyce. Popište akci – „postava mává“, „zombie se táhne vpřed“ – a obdržíte surový pohybový klip, který můžete přetargetovat na rigované postavy ve svém vlastním pipeline nebo v DCC nástrojích.

Výstupem je samostatný pohybový klip: nevyžaduje a není připojen k modelu postavy. Pokud potřebujete nejprve rigovat postavu, podívejte se na Rigging API.

POST/openapi/v1/text-to-motion

Vytvoření úkolu pro převod textu na pohyb

Tento endpoint vytvoří nový úkol pro generování pohybového klipu z textového promptu.

Úkol s mode prime stojí 10 kreditů a generuje s naším nejkvalitnějším pohybovým modelem. Úkol s mode swift stojí 3 kredity a generuje rychleji s naším ekonomickým pohybovým modelem.

Parametry

Name
prompt
Type
string
Povinné
Description
Popis pohybu, který má být generován, v přirozeném jazyce. Maximálně 400 znaků.
Name
mode
Type
string
výchozí prime
Description
Režim generování pohybu. Dostupné hodnoty: prime, swift. prime produkuje 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ého klipu v sekundách. Mezi 2 a 10, v krocích po 0.5 (například 2, 2.5, 3, … 10).

Vrací

Vlastnost result odpovědi obsahuje id nově vytvořeného úkolu pro převod textu na pohyb.

Režimy selhání

Name
400 - Bad Request
Description
Požadavek nebyl přijatelný. Časté příčiny:
- Chybějící nebo prázdný prompt: prompt chybí, je prázdný nebo delší než 400 znaků.
- Neplatný režim: mode není prime ani swift.
- Neplatná délka: duration chybí, je mimo rozsah 2–10 nebo není na kroku 0.5 sekundy.
Name
401 - Unauthorized
Description
Autentizace selhala. Zkontrolujte prosím svůj API klíč.
Name
402 - Payment Required
Description
Nedostatečné kredity pro provedení tohoto úkolu.
Name
403 - Forbidden
Description
Prompt byl označen moderací obsahu.
Name
429 - Too Many Requests
Description
Překročili jste svůj limit rychlosti.

Požadavek

POST

/openapi/v1/text-to-motion

# Generování pohybového klipu pouze s povinnými parametry
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
  }'

# Generování rychlého, ekonomického klipu s režimem 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
  }'

Odpověď

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

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

Načíst úkol Text to Motion

Tento koncový bod umožňuje načíst úkol Text to Motion s platným id úkolu. Podívejte se na Objekt úkolu Text to Motion, abyste zjistili, které vlastnosti jsou zahrnuty.

Parametry

Name
id
Type
path
Description
Unikátní identifikátor pro úkol Text to Motion, který má být načten.

Vrací

Odezva obsahuje objekt úkolu Text to Motion. Podívejte se do sekce Objekt úkolu Text to Motion pro podrobnosti.

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

Seznam úkolů Text to Motion

Vrací stránkovaný seznam uživatelových úkolů Text to Motion, od nejnovějších. Standardní stránkování pomocí page_num a page_size.

Odpověď je pole Text to Motion Task objektů.

Uvědomte si, že úkoly vytvořené přes API jsou spravovány přes API — nezobrazují se v My Assets webové aplikace. Použijte tento endpoint k nalezení úkolu, jehož ID už 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í úkolu Text to Motion

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

Parametry

Name
id
Type
path
Description
Unikátní identifikátor pro úkol Text to Motion ke streamování.

Návratové hodnoty

Vrací stream Objektů úkolu Text to Motion jako Server-Sent Events.

Každá message událost nese celý objekt úkolu. Když je úkol PENDING nebo IN_PROGRESS, pole result jsou stále prázdná ("" / 0) a finished_at / expires_at jsou 0; sledujte status a progress.

Požadavek

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

// Ukázka události s chybou
event: error
data: {
  "status_code": 404,
  "message": "Úkol nebyl nalezen"
}

// Události typu message nesou celý objekt úkolu v každé fázi; pole result
// zůstanou prázdná, dokud úkol nedosáhne úspěchu.
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: { // Příklad položky streamu úspěšného úkolu, zrcadlící strukturu Objektu úkolu Text to Motion
  "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ě generovaného pohybového klipu. Tato akce je nevratná.

Parametry cesty

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

Vrací

Vrací 200 OK při úspěchu.

Požadavek

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

// Vrací 200 Ok při úspěšném dokončení.

Objekt úkolu Text to Motion

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

Vlastnosti

Name
id
Type
string
Description
Unikátní identifikátor pro úkol.
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
Postup úkolu (0-100).
Name
created_at
Type
timestamp
Description
Časové razítko (milisekundy od epochy), kdy byl úkol vytvořen.
Časové razítko představuje počet milisekund uplynulých od 1. ledna 1970 UTC v souladu s RFC 3339 standardem. Například pátek, 1. září 2023 12:00:00 GMT je reprezentováno jako 1693569600000. To platí pro všechna časová razítka v Meshy API.
Name
started_at
Type
timestamp
Description
Časové razítko (milisekundy od epochy), kdy zpracování úkolu začalo. 0, pokud nezačalo.
Name
finished_at
Type
timestamp
Description
Časové razítko (milisekundy od epochy), kdy úkol skončil. 0, pokud není dokončen.
Name
expires_at
Type
timestamp
Description
Časové razítko (milisekundy od epochy), kdy vyprší platnost výsledných assetů úkolu. 0 do dokončení úkolu. Generovaný klip je uchován 3 dny po dokončení úkolu; stáhněte ho před vypršením.
Name
preceding_tasks
Type
integer
Description
Počet předcházejících úkolů ve frontě. Významné pouze, pokud je stav PENDING; vynecháno, pokud je nula.
Name
consumed_credits
Type
integer
Description
Počet kreditů spotřebovaných tímto úkolem. 10 pro prime mode, 3 pro swift mode. Vrací 0 pro úkoly FAILED (kredity jsou v případě selhání vráceny).
Name
task_error
Type
object
Description
Podrobnosti o chybách pro neúspěšné úkoly; null, pokud úkol není FAILED. Viz Chyby pro úplnou referenci objektu task_error.
Name
result
Type
object
Description
Obsahuje generovaný pohybový klip, jakmile úkol SUCCEEDED; do té doby jsou pole přítomna, ale prázdná ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Stáhnutelná URL pro generovaný pohybový klip. URL je znovu podepisována při každém čtení a vyprší s časovým oknem úkolu.
- Name
  motion_format
  Type
  string
  Description
  Formát souboru klipu: fbx pro prime mode, bvh pro swift mode.
- Name
  duration_ms
  Type
  integer
  Description
  Délka generovaného klipu v milisekundách.
- Name
  mode
  Type
  string
  Description
  Režim, ve kterém byl klip generován: prime nebo swift.

Příklad objektu úkolu Text to Motion

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