Text till Rörelse API

Generera karaktärsrörelseklipp från naturliga språkbeskrivningar. Beskriv en handling — "en karaktär vinkar", "en zombie haltar framåt" — och få ett rått rörelseklipp som du kan retargetta på riggade karaktärer i din egen pipeline eller DCC-verktyg.

Utdata är ett fristående rörelseklipp: det kräver inte, och är inte kopplat till, en karaktärsmodell. För att rigga en karaktär först, se Riggnings-API.

POST/openapi/v1/text-to-motion

Skapa en Text till Rörelse Uppgift

Denna endpoint skapar en ny uppgift för att generera ett rörelseklipp från en textprompt.

En uppgift med mode prime kostar 10 credits och genererar med vår högsta kvalitets rörelsemodell. En uppgift med mode swift kostar 3 credits och genererar snabbare med vår ekonomiska rörelsemodell.

Parametrar

Name
prompt
Type
string
Obligatorisk
Description
En beskrivning i naturligt språk av rörelsen som ska genereras. Max 400 tecken.
Name
mode
Type
string
standard prime
Description
Läge för rörelsegenerering. Tillgängliga värden: prime, swift. prime ger högsta kvalitet och levererar FBX; swift är snabbare och billigare och levererar BVH.
Name
duration
Type
number
Obligatorisk
Description
Måldurationen för rörelseklippet i sekunder. Mellan 2 och 10, i steg om 0.5 (till exempel 2, 2.5, 3, … 10).

Återkommer

result egenskapen av svaret innehåller uppgiftens id för den nyligen skapade Text till Rörelse uppgiften.

Felmodi

Name
400 - Bad Request
Description
Begäran var oacceptabel. Vanliga orsaker:
- Saknad eller tom prompt: prompt saknas, är tom eller längre än 400 tecken.
- Ogiltigt mode: mode är inte prime eller swift.
- Ogiltig duration: duration saknas, utanför 2–10, eller inte på en 0.5 sekunders steg.
Name
401 - Unauthorized
Description
Autentisering misslyckades. Vänligen kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckliga credits för att utföra denna uppgift.
Name
403 - Forbidden
Description
Prompta flaggades av innehållsmoderering.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.

Request

POST

/openapi/v1/text-to-motion

# Generera ett rörelseklipp med endast nödvändiga parametrar
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
  }'

# Generera ett snabbt, ekonomiskt klipp med 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

Hämta en Text till Rörelse-uppgift

Denna endpoint gör det möjligt för dig att hämta en Text till Rörelse-uppgift givet ett giltigt uppdrags-id. Se Text till Rörelse-uppgiftsobjektet för att se vilka egenskaper som ingår.

Parametrar

Name
id
Type
path
Description
Unik identifierare för Text till Rörelse-uppgiften att hämta.

Returnerar

Svaret innehåller Text till Rörelse-uppgiftsobjektet. Kontrollera avsnittet Text till Rörelse-uppgiftsobjektet för detaljer.

Förfrågan

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

Svar

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

Lista över Text till Rörelse-uppgifter

Returnerar en paginerad lista av anroparens Text till Rörelse-uppgifter, nyaste först. Standardpaginering via page_num och page_size.

Svaret är en array av Text till Rörelse-uppgiftsobjekt.

Observera att uppgifter skapade via API:et hanteras genom API:et — de visas inte i webbappens Mina Tillgångar. Använd denna endpoint för att hitta en uppgift vars ID du inte längre har.

Begäran

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

Svar

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

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

Streama en Text to Motion-uppgift

Detta endpoint strömmar realtidsuppdateringar för en Text to Motion-uppgift via Server-Sent Events (SSE).

Parametrar

Name
id
Type
path
Description
Unik identifierare för Text to Motion-uppgiften att strömma.

Returnerar

Returnerar en ström av The Text to Motion Task Objects som Server-Sent Events.

Varje message-händelse innehåller hela uppgiftsobjektet. Medan uppgiften är PENDING eller IN_PROGRESS är result-fälten fortfarande tomma ("" / 0) och finished_at / expires_at är 0; håll koll på status och progress.

Förfrågan

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

Svarström

// Exempel på felhändelse
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Meddelandehändelser bär hela uppgiftsobjektet i varje steg; resultatfälten
// förblir tomma tills uppgiften lyckas.
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: { // Exempel på en SUCCEEDED-uppgiftsströmspost, som speglar Text to Motion Task Object-strukturen
  "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

Ta bort en Text till Motion-uppgift

Detta endpoint tar permanent bort en Text till Motion-uppgift, inklusive det genererade videoklippet. Denna åtgärd kan inte återställas.

Sökvärden

Name
id
Type
path
Description
ID för den Text till Motion-uppgift som ska tas bort.

Returnerar

Returnerar 200 OK vid framgång.

Begäran

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

Svar

// Returnerar 200 Ok vid framgång.

Objektet Text to Motion Task

Objektet Text to Motion Task representerar arbetsenheten för att generera ett rörelseklipp från en textprompt.

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften.
Name
type
Type
string
Description
Typ av uppgift. Värdet är text-to-motion.
Name
status
Type
string
Description
Status för uppgiften. Möjliga värden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Framsteg av uppgiften (0-100).
Name
created_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoken) när uppgiften skapades.
En tidsstämpel representerar antalet millisekunder som har passerat sedan den 1 januari 1970 UTC, enligt RFC 3339-standarden. Till exempel representeras fredag, 1 september 2023 12:00:00 GMT som 1693569600000. Detta gäller för alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoken) när uppgiften började bearbetas. 0 om inte startad.
Name
finished_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoken) när uppgiften avslutades. 0 om inte avslutad.
Name
expires_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoken) när resultatet för assets för uppgiften går ut. 0 tills uppgiften är avslutad. Det genererade klippet hålls kvar i 3 dagar efter att uppgiften är avslutad; ladda ner det innan det går ut.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter i kön. Meningsfullt endast om statusen är PENDING; utelämnas när den är noll.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. 10 för prime mode, 3 för swift mode. Returnerar 0 för FAILED tasks (credits återbetalas vid fel).
Name
task_error
Type
object
Description
Felinformation för misslyckade uppgifter; null om inte uppgiften FAILED. Se Fel för den fullständiga referensen av task_error-objektet.
Name
result
Type
object
Description
Innehåller det genererade rörelseklippet när uppgiften SUCCEEDED; tills dess är fälten närvarande men tomma ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Nerladdningsbar URL för det genererade rörelseklippet. URL:en omtecknas vid varje läsning och går ut med uppgiftens restenstid.
- Name
  motion_format
  Type
  string
  Description
  Filformat för klippet: fbx för prime mode, bvh för swift mode.
- Name
  duration_ms
  Type
  integer
  Description
  Varaktighet av det genererade klippet i millisekunder.
- Name
  mode
  Type
  string
  Description
  Mode som klippet genererades med: prime eller swift.

Exempel på 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
}