Animatie-API

Endpoints voor het ontdekken van beschikbare animaties en het toepassen ervan op characters met een rig.

POST/openapi/v1/animations

Create an Animation Task

Met deze endpoint kunt u een nieuwe taak aanmaken om een animatie toe te passen op een eerder gerigd personage — hetzij een vooraf ingestelde actie uit de animatiebibliotheek (action_id), hetzij een motion clip die u hebt gegenereerd met de Text to Motion API (motion_task_id). Inclusief opties voor nabewerking.

Parameters

Name
rig_task_id
Type
string
Verplicht
Description
De id van een succesvol afgeronde rigging-taak (van POST /openapi/v1/rigging). Het personage van deze taak wordt geanimeerd.
Name
action_id
Type
integer
Description
De identifier van de vooraf ingestelde animatie-actie die moet worden toegepast. Zie de Animation Library Reference voor een volledige lijst van beschikbare animaties. Geef precies één van action_id of motion_task_id op.
Name
motion_task_id
Type
string
Description
De id van een succesvol afgeronde Text to Motion-taak die moet worden toegepast in plaats van een vooraf ingestelde actie. De gegenereerde clip wordt geretarget naar het gerigde personage en de clip wordt op het moment van aanmaken vastgelegd als momentopname, zodat deze taak niet wordt beïnvloed als de bron-taak later verloopt of wordt verwijderd. De assets van de bron-taak worden 3 dagen bewaard — pas de clip toe voordat deze verloopt. Vereist een biped rig. Geef precies één van action_id of motion_task_id op.
Name
post_process
Type
object
Description
Optionele nabewerking voor de animatie-uitvoer. Laat dit weg om de standaard animatiebestanden te ontvangen.

Alleen van toepassing wanneer post_process is set

Name
operation_type
Type
string
Verplicht
Description
Het type bewerking dat moet worden uitgevoerd. Beschikbare waarden: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
standaard 30
Description
De gewenste framerate. Alleen van toepassing wanneer operation_type gelijk is aan change_fps. Toegestane waarden: 24, 25, 30, 60.

Bij motion_task_id kan het retargeten resulteren in een animatie die alleen als GLB beschikbaar is. Als u post_process heeft aangevraagd en er geen FBX beschikbaar is, mislukt de taak met een task_error en worden uw credits automatisch terugbetaald; zonder post_process slaagt de taak en is animation_fbx_url leeg.

Retourwaarden

De result-property van de response bevat de taak-id van de nieuw aangemaakte animatietaak.

Foutmodi

Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
- Ontbrekende parameter: rig_task_id ontbreekt, of noch action_id noch motion_task_id is opgegeven.
- Conflicterende parameters: zowel action_id als motion_task_id zijn opgegeven — deze sluiten elkaar wederzijds uit.
- Ongeldige rig-taak: De rig_task_id is ongeldig of verwijst naar een mislukte/niet-bestaande taak.
- Ongeldige action ID: De action_id komt niet overeen met een geldige animatie.
- Motion-taak nog niet gereed: de taak bij motion_task_id heeft nog niet de status SUCCEEDED.
- Niet-ondersteunde rig: motion_task_id vereist een biped rig; quadruped rigs worden geweigerd.
Name
401 - Unauthorized
Description
Authenticatie mislukt. Controleer uw API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
404 - Not Found
Description
De rigging-taak die is opgegeven met rig_task_id is niet gevonden, de motion-taak die is opgegeven met motion_task_id is niet gevonden, of de motion clip is verlopen (bron-taak assets worden 3 dagen bewaard).
Name
429 - Too Many Requests
Description
U heeft uw rate limit overschreden.

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

Een animatietaak ophalen

Deze endpoint stelt u in staat om een animatietaak op te halen met een geldige taak-id. Raadpleeg The Animation Task Object om te zien welke eigenschappen zijn opgenomen.

Parameters

Name
id
Type
path
Description
Unieke identifier voor de animatietaak die moet worden opgehaald.

Retourneert

De respons bevat het Animation Task-object. Raadpleeg de sectie The Animation Task Object voor details.

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

Een Animatietaak verwijderen

Deze endpoint verwijdert permanent een animatietaak, inclusief alle bijbehorende modellen en gegevens. Deze actie is onomkeerbaar.

Padparameters

Name
id
Type
path
Description
De ID van de animatietaak die verwijderd moet worden.

Retourneert

Retourneert 200 OK bij succes.

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

Lijst met animatietaken opvragen

Geeft een gepagineerde lijst van de animatietaken van de aanroeper terug, nieuwste eerst. Standaard paginering via page_num en page_size.

Merk op dat taken die via de API zijn aangemaakt, ook via de API worden beheerd — ze verschijnen niet in Mijn assets van de web-app. Gebruik deze endpoint om een taak te vinden waarvan je de ID niet meer hebt.

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

Stream een Animatietaak

Deze endpoint streamt realtime updates voor een Animatietaak via Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unieke identificatie voor de Animatietaak die gestreamd moet worden.

Retourneert

Retourneert een stream van The Animation Task Objects als Server-Sent Events.

Voor taken met status PENDING of IN_PROGRESS bevat de responsstream alleen de noodzakelijke velden progress en 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

Het Animation Task-object vertegenwoordigt de werkeenheid voor het toepassen van een animatie op een gerigd personage.

Eigenschappen

Name
id
Type
string
Description
Unieke identifier voor de taak.
Name
type
Type
string
Description
Type van de Animatie-taak. De waarde is animate.
Name
status
Type
string
Description
Status van de taak. Mogelijke waarden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Voortgang van de taak (0-100).
Name
created_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak is aangemaakt.
Een tijdstempel vertegenwoordigt het aantal milliseconden dat is verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339-standaard. Vrijdag 1 september 2023 12:00:00 GMT wordt bijvoorbeeld weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in de Meshy API.
Name
started_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak is begonnen met verwerken. 0 als deze nog niet is gestart.
Name
finished_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak is voltooid. 0 als deze nog niet is voltooid.
Name
expires_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de resultaat-assets van de taak verlopen.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat door deze taak is verbruikt. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS of SUCCEEDED is. Retourneert 0 voor FAILED-taken (credits worden terugbetaald bij mislukking).
Name
result
Type
object
Description
Bevat de URL's van de uitvoeranimatie als de taak SUCCEEDED is.
- Name
  animation_glb_url
  Type
  string
  Description
  Downloadbare URL voor de animatie in GLB-formaat.
- Name
  animation_fbx_url
  Type
  string
  Description
  Downloadbare URL voor de animatie in FBX-formaat.
- Name
  processed_usdz_url
  Type
  string
  Description
  Downloadbare URL voor de verwerkte animatie in USDZ-formaat.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Downloadbare URL voor de verwerkte armature in FBX-formaat.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Downloadbare URL voor de animatie met gewijzigde FPS in FBX-formaat (bijvoorbeeld als de bewerking change_fps is gebruikt).
Name
preceding_tasks
Type
integer
Description
Het aantal voorgaande taken in de wachtrij. Alleen relevant als de status PENDING is.

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
}