Text till rörelse-API

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

Utdatan är ett fristående rörelseklipp: det kräver inte, och är inte kopplat till, en karaktärsmodell. För att först rigga en karaktär, se Rigging API. För att applicera ett genererat klipp på din riggade karaktär, skicka uppgifts-id som motion_task_id till Animation API — applicera det inom det 3-dagars långa fönstret för tillgångslagring.

POST/openapi/v1/text-to-motion

Skapa en Text till Motion-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 kvalitetsmodell för rörelse. 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. Maximalt 400 tecken.
Name
mode
Type
string
standard prime
Description
Läget för rörelsegenerering. Tillgängliga värden: prime, swift. prime ger högsta kvalitet och genererar FBX; swift är snabbare och billigare och genererar BVH.
Name
duration
Type
number
Obligatorisk
Description
Målets varaktighet för rörelseklippet i sekunder. Mellan 2 och 10, i steg om 0.5 (till exempel 2, 2.5, 3, … 10).

Returnerar

Egenskapen result i svaret innehåller uppgifts-id för den nyligen skapade Text till Motion-uppgiften.

Felscenarier

Name
400 - Bad Request
Description
Begäran kunde inte accepteras. Vanliga orsaker:
- Saknad eller tom prompt: prompt saknas, är tom eller längre än 400 tecken.
- Ogiltigt mode: mode är varken prime eller swift.
- Ogiltig duration: duration saknas, ligger utanför 2–10, eller följer inte ett steg om 0.5 sekunder.
Name
401 - Unauthorized
Description
Autentiseringen misslyckades. Kontrollera din API-nyckel.
Name
402 - Payment Required
Description
Otillräckligt med credits för att utföra denna uppgift.
Name
403 - Forbidden
Description
Prompten flaggades av innehållsmoderationen.
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.

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

Hämta en Text till Motion-uppgift

Denna endpoint låter dig hämta en Text till Motion-uppgift givet ett giltigt uppgifts-id. Se The Text to Motion Task Object för att se vilka egenskaper som ingår.

Parametrar

Name
id
Type
path
Description
Unik identifierare för den Text till Motion-uppgift som ska hämtas.

Returnerar

Svaret innehåller Text till Motion Task-objektet. Se avsnittet The Text to Motion Task Object för detaljer.

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

Lista Text to Motion-uppgifter

Returnerar en paginerad lista över anroparens Text to Motion-uppgifter, nyaste först. Standardpaginering via page_num och page_size.

Svaret är en array av Text to Motion Task-objekt.

Observera att uppgifter som skapas via API:et hanteras via 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.

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

Streama en Text to Motion-uppgift

Denna endpoint strömmar realtidsuppdateringar för en Text to Motion-uppgift med hjälp av Server-Sent Events (SSE).

Parametrar

Name
id
Type
path
Description
Unik identifierare för den Text to Motion-uppgift som ska strömmas.

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 fälten under result fortfarande tomma ("" / 0) och finished_at / expires_at är 0; håll koll på status och 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

Ta bort en Text till rörelse-uppgift

Denna endpoint tar permanent bort en Text till rörelse-uppgift, inklusive det genererade rörelseklippet. Denna åtgärd är oåterkallelig.

Sökvägsparametrar

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

Returnerar

Returnerar 200 OK vid lyckad 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

// Returns 200 Ok on success.

The Text to Motion Task Object

Text to Motion Task-objektet 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
Uppgiftens typ. Värdet är text-to-motion.
Name
status
Type
string
Description
Uppgiftens status. Möjliga värden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Uppgiftens progress (0-100).
Name
created_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) för när uppgiften skapades.
En tidsstämpel representerar antalet millisekunder som förflutit sedan 1 januari 1970 UTC, enligt standarden RFC 3339. Till exempel representeras fredagen den 1 september 2023 kl. 12:00:00 GMT som 1693569600000. Detta gäller alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) för när uppgiften började bearbetas. 0 om den inte har startat.
Name
finished_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) för när uppgiften slutfördes. 0 om den inte är klar.
Name
expires_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) för när uppgiftens resultattillgångar upphör att gälla. 0 tills uppgiften är klar. Det genererade klippet sparas i 3 dagar efter att uppgiften är klar; ladda ner det innan det upphör att gälla.
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter i kön. Meningsfullt endast om statusen är PENDING; utelämnas när värdet ä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 uppgifter med status FAILED (credits återbetalas vid fel).
Name
task_error
Type
object
Description
Felinformation för misslyckade uppgifter; null om inte uppgiften har status FAILED. Se Fel för den fullständiga referensen för task_error-objektet.
Name
result
Type
object
Description
Innehåller det genererade rörelseklippet när uppgiften har status SUCCEEDED; fram tills dess finns fälten med men är tomma ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Nedladdningsbar URL för det genererade rörelseklippet. URL:en signeras om vid varje läsning och upphör att gälla i samband med uppgiftens lagringsperiod.
- Name
  motion_format
  Type
  string
  Description
  Klippets filformat: fbx för prime-mode, bvh för swift-mode.
- Name
  duration_ms
  Type
  integer
  Description
  Det genererade klippets längd i millisekunder.
- Name
  mode
  Type
  string
  Description
  Det mode klippet genererades med: prime eller 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
}