Animation API

Endpoints för att upptäcka tillgängliga animationer och applicera dem på riggade karaktärer.

POST/openapi/v1/animations

Skapa en animationsuppgift

Denna endpoint gör det möjligt att skapa en ny uppgift för att tillämpa en animation på en tidigare riggad karaktär — antingen en förinställd åtgärd från animationsbiblioteket (action_id) eller ett rörelseklipp du genererat med Text to Motion API (motion_task_id). Inkluderar alternativ för efterbehandling.

Parametrar

Name
rig_task_id
Type
string
Obligatorisk
Description
id för en framgångsrikt slutförd riggningsuppgift (från POST /openapi/v1/rigging). Karaktären från denna uppgift kommer att animeras.
Name
action_id
Type
integer
Description
Identifieraren för den förinställda animationsåtgärd som ska tillämpas. Se Animation Library Reference för en fullständig lista över tillgängliga animationer. Ange exakt en av action_id eller motion_task_id.
Name
motion_task_id
Type
string
Description
id för en framgångsrikt slutförd Text to Motion-uppgift att tillämpa istället för en förinställd åtgärd. Det genererade klippet omriktas till den riggade karaktären och klippet tas som en ögonblicksbild vid skapandet, så denna uppgift påverkas inte om källuppgiften senare upphör att gälla eller raderas. Källuppgiftens tillgångar behålls i 3 dagar — tillämpa klippet innan det upphör att gälla. Kräver en tvåfotad rigg. Ange exakt en av action_id eller motion_task_id.
Name
post_process
Type
object
Description
Valfri efterbehandling för animationsutdatan. Utelämna den för att erhålla de standardmässiga animationsfilerna.

Gäller endast när post_process is set

Name
operation_type
Type
string
Obligatorisk
Description
Typen av åtgärd som ska utföras. Tillgängliga värden: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
standard 30
Description
Målbildhastigheten. Gäller endast när operation_type är change_fps. Tillåtna värden: 24, 25, 30, 60.

Med motion_task_id kan omriktningen resultera i en animation som endast finns i GLB. Om du begärde post_process och ingen FBX är tillgänglig misslyckas uppgiften med ett task_error och dina credits återbetalas automatiskt; utan post_process lyckas uppgiften och animation_fbx_url är tom.

Returer

Egenskapen result i svaret innehåller id för den nyligen skapade animationsuppgiften.

Felscenarier

Name
400 - Bad Request
Description
Begäran var oacceptabel. Vanliga orsaker:
- Saknad parameter: rig_task_id saknas, eller varken action_id eller motion_task_id har angetts.
- Konflikterande parametrar: både action_id och motion_task_id har angetts — de är ömsesidigt uteslutande.
- Ogiltig riggningsuppgift: rig_task_id är ogiltig eller refererar till en misslyckad/icke-existerande uppgift.
- Ogiltigt action-ID: action_id motsvarar inte en giltig animation.
- Rörelseuppgift inte redo: motion_task_id-uppgiften har ännu inte blivit SUCCEEDED.
- Rigg stöds inte: motion_task_id kräver en tvåfotad rigg; fyrfotade riggar avvisas.
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
404 - Not Found
Description
Riggningsuppgiften som angetts av rig_task_id hittades inte, rörelseuppgiften som angetts av motion_task_id hittades inte, eller rörelseklippet har upphört att gälla (källuppgiftens tillgångar behålls i 3 dagar).
Name
429 - Too Many Requests
Description
Du har överskridit din hastighetsgräns.

Request

POST

/openapi/v1/animations

# Animate a rigged model with required params only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92
  }'

# Apply a generated Text to Motion clip instead of a preset action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
  }'

# With post-processing to change FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 24
    }
  }'

Response

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

GET/openapi/v1/animations/:id

Hämta en Animation-uppgift

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

Parametrar

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

Returer

Svaret innehåller Animation Task-objektet. Se avsnittet The Animation Task Object för detaljer.

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/animations/:id

Ta bort en Animation-uppgift

Denna endpoint tar permanent bort en Animation-uppgift, inklusive alla associerade modeller och data. Denna åtgärd är oåterkallelig.

Sökvägsparametrar

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

Returer

Returnerar 200 OK vid lyckad borttagning.

Request

DELETE

/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/animations

Lista animationsuppgifter

Returnerar en paginerad lista över den anropande partens animationsuppgifter, nyaste först. Standardpaginering via page_num och page_size.

Observera att uppgifter som skapats 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/animations

curl "https://api.meshy.ai/openapi/v1/animations?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/animations/:id/stream

Streama en Animation-uppgift

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

Parametrar

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

Returer

Returnerar en ström av The Animation Task Objects som Server-Sent Events.

För uppgifter med status PENDING eller IN_PROGRESS kommer svarsströmmen endast att innehålla nödvändiga fält för progress och status.

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/animations/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 event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Animation Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

The Animation Task Object

Animation Task-objektet representerar arbetsenheten för att applicera en animation på en riggad karaktär.

Egenskaper

Name
id
Type
string
Description
Unik identifierare för uppgiften.
Name
type
Type
string
Description
Typ av Animation-uppgift. Värdet är animate.
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) när uppgiften skapades.
En tidsstämpel representerar antalet millisekunder som förflutit sedan den 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 för alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiften började bearbetas. 0 om den inte har startat.
Name
finished_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiften slutfördes. 0 om den inte är klar.
Name
expires_at
Type
timestamp
Description
Tidsstämpel (millisekunder sedan epoch) när uppgiftens resultattillgångar upphör att gälla.
Name
task_error
Type
object
Description
Feldetaljer för misslyckade uppgifter. Se Fel för den fullständiga referensen för task_error-objektet.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukats av denna uppgift. Finns när uppgiftens status är PENDING, IN_PROGRESS, eller SUCCEEDED. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel).
Name
result
Type
object
Description
Innehåller URL:er för de resulterande animationerna om uppgiften SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  Nedladdningsbar URL för animationen i GLB-format.
- Name
  animation_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för animationen i FBX-format.
- Name
  processed_usdz_url
  Type
  string
  Description
  Nedladdningsbar URL för den bearbetade animationen i USDZ-format.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för den bearbetade armaturen i FBX-format.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Nedladdningsbar URL för animationen med ändrad FPS i FBX-format (t.ex. om change_fps-operationen användes).
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter i kön. Endast relevant om status är PENDING.

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}