Text to Motion API

Generera rörelseklipp för karaktärer från textbeskrivningar. Beskriv en handling, till exempel "en karaktär som vinkar" eller "en zombie som släpar sig framåt", och få ett rått rörelseklipp. Du kan retargeta klippet till riggade karaktärer i din egen pipeline eller dina DCC-verktyg.

Utdatan är ett fristående rörelseklipp. Det behöver ingen karaktärsmodell och är inte kopplat till någon. För att först rigga en karaktär, se Rigging API. För att applicera ett klipp på din riggade karaktär, skicka uppgiftens id som motion_task_id till Animation API.

POST/openapi/v1/text-to-motion

Skapa en Text till rörelse-uppgift

Skapar en Text till rörelse-uppgift, som genererar ett rörelseklipp från en textprompt.

Uppgiften körs i bakgrunden. För information om hur lång tid en uppgift vanligtvis tar, se Bearbetningstider.

En prime-uppgift kostar 10 credits och använder Meshys rörelsemodell av högre kvalitet. En swift-uppgift kostar 3 credits och använder en snabbare, billigare rörelsemodell.

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

Parametrar

Name
prompt
Type
string
Obligatorisk
Description
Text som beskriver rörelsen som ska genereras, upp till 400 tecken. Längre text returnerar 400.
Name
mode
Type
string
standard prime
Description
Rörelsemodellen, som även avgör klippets filformat.
Tillgängliga värden:
- prime: högre kvalitet, returnerar ett FBX-klipp
- swift: snabbare och billigare, returnerar ett BVH-klipp
Alla andra värden returnerar 400.
Name
duration
Type
number
Obligatorisk
Description
Mållängden för klippet i sekunder, från 2 till 10 i steg om 0.5, till exempel 2, 2.5 eller 3. Alla andra värden returnerar 400.

Returnerar

Fältet result i svaret innehåller ID:t för den nya Text till rörelse-uppgiften.

Felscenarion

Name
400 - Bad Request
Description
Begäran kan inte köras. Felmeddelandet anger vilket problem som hittades. Till exempel:
- Saknad eller tom prompt: prompt saknas, är tom eller är längre än 400 tecken.
- Ogiltig mode: mode är varken prime eller swift.
- Ogiltig duration: duration saknas, ligger utanför intervallet 2 till 10, eller följer inte ett steg om 0.5 sekunder.
Åtgärda begäran och skicka den sedan igen. Se Fel.
Name
401 - Unauthorized
Description
API-nyckeln saknas eller är ogiltig. Kontrollera Authorization-headern.
Name
402 - Payment Required
Description
Till exempel:
- Otillräckligt med credits: Kontot har inte tillräckligt med credits för den här uppgiften, eller kontot har nått en creditgräns. Kontrollera ditt saldo och försök sedan igen.
- Gratisplan: Att skapa en uppgift kräver en betald plan. Uppgradera din plan i dina prenumerationsinställningar och försök sedan igen.
Name
403 - Forbidden
Description
Innehållsmoderationen flaggade prompten. Ändra prompten och skicka sedan begäran igen.
Name
429 - Too Many Requests
Description
Du överskred din hastighetsgräns. Vänta och försök sedan igen. Se Hastighetsgränser.

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

Hämta en Text till Motion-uppgift

Returnerar en Text till Motion-uppgift baserat på dess 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
}

Parametrar

Name
id
Type
path
Description
Uppgifts-ID från svaret vid skapandet.

Returnerar

Text till Motion-uppgiftsobjektet.

GET/openapi/v1/text-to-motion

Lista uppgifter för Text to Motion

Returnerar en paginerad lista över dina Text to Motion-uppgifter, nyaste först. För att bläddra genom listan, använd page_num och page_size.

Svaret är en array med Text to Motion-uppgiftsobjekt.

Uppgifter du skapar med API:et stannar i API:et och visas inte i Mina tillgångar i webbappen. Använd denna endpoint för att hitta en uppgift vars ID du inte längre har.

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

Strömma en Text till Motion-uppgift

Strömmar uppdateringar för en Text till Motion-uppgift som 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
}

Parametrar

Name
id
Type
path
Description
Uppgifts-ID:t från skapandesvaret.

Returnerar

En ström av Text till Motion-uppgiftsobjekt som Server-Sent Events.

Varje message-händelse innehåller hela uppgiftsobjektet. Medan uppgiften är PENDING eller IN_PROGRESS är result-fälten tomma ("" eller 0), och finished_at och expires_at är 0. För att följa uppgiften, bevaka status och progress.

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

Ta bort en Text till rörelse-uppgift

Tar bort en Text till rörelse-uppgift permanent, inklusive dess rörelseklipp. Du kan inte ångra en borttagning.

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

Sökvägsparametrar

Name
id
Type
path
Description
ID:t för uppgiften som ska tas bort.

Uppgiftsstatus

Att ta bort en uppgift med status PENDING återbetalar de credits som användes när du skapade den.

En uppgift med status IN_PROGRESS kan inte tas bort. Förfrågan returnerar 409 Conflict, och uppgiften fortsätter att köras. Meshy återbetalar inte en uppgift som har påbörjats, så att ta bort den skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

Att ta bort en uppgift med en slutgiltig status (SUCCEEDED, FAILED eller CANCELED) återbetalar inte dess credits.

Returnerar

200 OK när uppgiften är borttagen, eller 409 Conflict när uppgiften är IN_PROGRESS.

The Text to Motion task object

Ett Text to Motion-uppgiftsobjekt beskriver genereringen av ett rörelseklipp. Det innehåller status, progress och klippet när uppgiften lyckas.

Egenskaper

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
Uppgifts-ID. Behandla det som en ogenomskinlig sträng och förlita dig inte på dess format.
Name
type
Type
string
Description
Uppgiftstypen, alltid text-to-motion.
Name
status
Type
string
Description
Uppgiftens status, en av PENDING, IN_PROGRESS, SUCCEEDED, FAILED eller CANCELED.
Name
progress
Type
integer
Description
Hur stor del av uppgiften som är klar, som en procentandel från 0 till 100.
Name
created_at
Type
timestamp
Description
Tidpunkt då uppgiften skapades, i Unix-millisekunder.
Name
started_at
Type
timestamp
Description
Tidpunkt då uppgiften startade, i Unix-millisekunder. Den är 0 tills uppgiften startar.
Name
finished_at
Type
timestamp
Description
Tidpunkt då uppgiften avslutades, i Unix-millisekunder. Den är 0 tills uppgiften avslutas.
Name
expires_at
Type
timestamp
Description
Tidpunkt då uppgiftens resultatfiler går ut, i Unix-millisekunder. Den är 0 tills uppgiften avslutas. Meshy sparar klippet i 3 dagar efter att uppgiften avslutats, så ladda ner det innan dess.
Name
preceding_tasks
Type
integer
Description
Antalet uppgifter före denna i kön. Värdet är meningsfullt endast medan uppgiften är PENDING. Fältet utelämnas när värdet är 0.
Name
consumed_credits
Type
integer
Description
Antalet credits som uppgiften förbrukade, 10 för prime-mode eller 3 för swift-mode. Det är 0 för en uppgift som är FAILED, eftersom Meshy återbetalar credits när en uppgift misslyckas.
Name
task_error
Type
object
Description
Felinformation när uppgiften misslyckas, och null annars. Se Fel.
Name
result
Type
object
Description
Det genererade rörelseklippet när uppgiften lyckas. Fram till dess finns fälten med men är tomma ("" eller 0).
- Name
  motion_url
  Type
  string
  Description
  Nedladdnings-URL för rörelseklippet. Meshy signerar URL:en på nytt vid varje läsning, och den går ut i samband med uppgiftens lagringsfönster.
- Name
  motion_format
  Type
  string
  Description
  Klippets filformat, fbx för prime-mode eller bvh för swift-mode.
- Name
  duration_ms
  Type
  integer
  Description
  Klippets längd, i millisekunder.
- Name
  mode
  Type
  string
  Description
  Det mode Meshy använde för att generera klippet, prime eller swift.