Animation API

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

POST/openapi/v1/animations

Skapa en Animation-uppgift

Denna endpoint låter dig skapa en ny uppgift för att tillämpa en specifik animationsåtgärd på en tidigare riggad karaktär. Inkluderar alternativ för efterbearbetning.

Parametrar

Name
rig_task_id
Type
string
Obligatorisk
Description
id för en slutförd rigging-uppgift (från POST /openapi/v1/rigging). Karaktären från denna uppgift kommer att animeras.
Name
action_id
Type
integer
Obligatorisk
Description
Identifieraren för den animationsåtgärd som ska tillämpas. Se referensen för Animationsbibliotek för en komplett lista över tillgängliga animationer.
Name
post_process
Type
object
Description
Valfri efterbearbetning för animationsutdata. Utelämna den för att få standardanimationsfilerna.

Gäller endast när post_process is set

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

Returnerar

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

Fellägen

Name
400 - Bad Request
Description
Begäran var oacceptabel. Vanliga orsaker:
- Saknad parameter: rig_task_id eller action_id saknas.
- Ogiltig rig-uppgift: rig_task_id är ogiltig eller hänvisar till en misslyckad/icke-existerande uppgift.
- Ogiltigt åtgärds-ID: action_id motsvarar inte en giltig animation.
Name
401 - Unauthorized
Description
Autentisering 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
Rigging-uppgiften som anges av rig_task_id hittades inte.
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
  }'

# 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 med ett giltigt uppgifts-id. Se Animation Task-objektet för att se vilka egenskaper som ingår.

Parametrar

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

Returnerar

Svaret innehåller Animation Task-objektet. Se avsnittet Animation Task-objektet för mer information.

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 animationsuppgift, inklusive alla associerade modeller och data. Denna åtgärd kan inte ångras.

Sökvägsparametrar

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

Returer

Returnerar 200 OK vid lyckat resultat.

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/:id/stream

Strömma en Animation-uppgift

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

Parametrar

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

Returnerar

Returnerar en ström av Animation-uppgiftsobjekten som Server-Sent Events.

För PENDING- eller IN_PROGRESS-uppgifter kommer svarsströmmen endast att inkludera nödvändiga progress- och status-fält.

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
}

Animation-uppgiftsobjektet

Animation-uppgiftsobjektet representerar arbetsenheten för att tillämpa en animation på en karaktär med rigg.

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
Status för uppgiften. Möjliga värden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
progress för uppgiften (0-100).
Name
created_at
Type
timestamp
Description
En tidsstämpel (millisekunder sedan epoken) när uppgiften skapades.
En tidsstämpel representerar antalet millisekunder som har förflutit sedan 1 januari 1970 UTC, enligt standarden RFC 3339. Till exempel representeras fredag 1 september 2023 12:00:00 PM GMT som 1693569600000. Detta gäller för alla tidsstämplar i Meshy API.
Name
started_at
Type
timestamp
Description
En tidsstämpel (millisekunder sedan epoken) när uppgiften började bearbetas. 0 om den inte har startat.
Name
finished_at
Type
timestamp
Description
En tidsstämpel (millisekunder sedan epoken) när uppgiften slutfördes. 0 om den inte är slutförd.
Name
expires_at
Type
timestamp
Description
En tidsstämpel (millisekunder sedan epoken) när uppgiftens resultat-assets upphör att gälla.
Name
task_error
Type
object
Description
Felinformation för misslyckade uppgifter. Se Fel för den fullständiga objektreferensen för task_error.
Name
consumed_credits
Type
integer
Description
Antalet credits som förbrukas 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:erna för utdata-animationen 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 armatur 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 operationen change_fps användes).
Name
preceding_tasks
Type
integer
Description
Antalet föregående uppgifter i kön. Meningsfullt endast 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
}