Animatie API

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

POST/openapi/v1/animations

Een Animatietaak Aanmaken

Met deze endpoint kun je een nieuwe taak aanmaken om een animatie toe te passen op een eerder gerigd personage — een vooraf ingestelde actie uit de animatiebibliotheek (action_id), meerdere vooraf ingestelde acties samengevoegd in één bestand (action_ids), of een motion clip die je hebt gegenereerd met de Text to Motion API (motion_task_id). Bevat opties voor nabewerking.

Parameters

Name
rig_task_id
Type
string
Verplicht
Description
De id van een succesvol voltooide rigging-taak (van POST /openapi/v1/rigging). Het personage uit deze taak wordt geanimeerd.
Name
action_id
Type
integer
Description
De identifier van de vooraf ingestelde animatieactie die moet worden toegepast. Zie de Animation Library Reference voor een volledige lijst van beschikbare animaties. Geef precies één van action_id, action_ids of motion_task_id op.
Name
action_ids
Type
array of integers
Description
Meerdere vooraf ingestelde animatieacties die in één keer worden toegepast, geretourneerd als één enkel bestand met per actie één animatieclip — handig om een personage aan te sturen vanuit een state machine in een game-engine. Geef 1 tot 10 action_id-waarden op uit de Animation Library Reference; id's moeten uniek zijn. Kost 3 credits per actie. Geef precies één van action_id, action_ids of motion_task_id op.
Het doorgeven van een action_ids met één element is gelijk aan het doorgeven van die waarde als action_id.
Name
motion_task_id
Type
string
Description
De id van een succesvol voltooide 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 (snapshot), 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, action_ids of motion_task_id op.
Name
post_process
Type
object
Description
Optionele nabewerking voor de animatie-output. 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 gebruik van action_ids retourneert de taak één samengevoegd bestand in plaats van één bestand per actie: animation_glb_url en animation_fbx_url verwijzen elk naar één enkel asset dat elke aangevraagde actie als afzonderlijke clip bevat.

Volgorde van clips: de volgorde van de action_ids-array, niet de numerieke volgorde van de id's.
Namen van clips: de naam van de animatie in de bibliotheek, overeenkomend met de namen die je krijgt bij het exporteren van alle animaties van een personage als één bestand vanuit de Meshy web-app. Als twee aangevraagde id's dezelfde clipnaam opleveren, krijgt de latere een achtervoegsel met zijn action_id om de namen uniek te houden.
Nabewerking: wordt toegepast op het samengevoegde bestand, niet op de afzonderlijke clips.

Bij gebruik van motion_task_id kan de retarget een animatie opleveren die alleen als GLB beschikbaar is. Als je post_process hebt aangevraagd en er geen FBX beschikbaar is, mislukt de taak met een task_error en worden je credits automatisch terugbetaald; zonder post_process slaagt de taak en is animation_fbx_url leeg.

Retourwaarden

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

Faalmodi

Name
400 - Bad Request
Description
Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:
- Ontbrekende parameter: rig_task_id ontbreekt, of geen van action_id, action_ids en motion_task_id is opgegeven.
- Conflicterende parameters: er is meer dan één van action_id, action_ids en motion_task_id 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: Een action_id — of een item uit action_ids — komt niet overeen met een geldige animatie.
- Te veel acties: action_ids bevat meer dan 10 id's.
- Dubbele acties: action_ids bevat hetzelfde id meer dan één keer.
- Motion-taak nog niet klaar: de taak met motion_task_id heeft nog geen status SUCCEEDED.
- Niet-ondersteunde rig: motion_task_id vereist een biped-rig; quadruped-rigs worden geweigerd.
Name
401 - Unauthorized
Description
Authenticatie is mislukt. Controleer je 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 via rig_task_id is niet gevonden, de motion-taak die is opgegeven via motion_task_id is niet gevonden, of de motion clip is verlopen (assets van de bron-taak worden 3 dagen bewaard).
Name
429 - Too Many Requests
Description
Je hebt je 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 several preset actions and get one file with one clip per 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",
    "action_ids": [10, 25, 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

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

Padparameters

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

Taakstatus

Een taak die nog PENDING is, wordt verwijderd en de credits die bij het aanmaken zijn verbruikt, worden terugbetaald.

Een taak die al IN_PROGRESS is, kan niet worden verwijderd: het verzoek wordt geweigerd met 409 Conflict en de taak blijft doorlopen. Credits voor een taak die de worker al is gestart, zijn niet terugbetaalbaar, dus het verwijderen ervan tijdens de uitvoering zou u zowel de credits als het resultaat kosten. Wacht tot de taak SUCCEEDED, FAILED of CANCELED bereikt, en verwijder deze dan.

Een taak in een eindstatus (SUCCEEDED, FAILED of CANCELED) wordt verwijderd zonder terugbetaling.

Retourneert

Retourneert 200 OK bij succes, of 409 Conflict wanneer de taak IN_PROGRESS is.

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

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
}

Het 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 identificatie 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 verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339-standaard. Bijvoorbeeld, vrijdag 1 september 2023 12:00:00 PM GMT wordt weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in Meshy API.
Name
started_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak begon te verwerken. 0 indien niet gestart.
Name
finished_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak is voltooid. 0 indien niet 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. Geeft 0 terug voor FAILED-taken (credits worden terugbetaald bij falen).
Name
result
Type
object
Description
Bevat de output-animatie-URL's als de taak SUCCEEDED is.
- Name
  animation_glb_url
  Type
  string
  Description
  Downloadbare URL voor de animatie in GLB-formaat. Voor een taak die met action_ids is aangemaakt, bevat dit ene bestand elke gevraagde actie als een aparte clip.
- Name
  animation_fbx_url
  Type
  string
  Description
  Downloadbare URL voor de animatie in FBX-formaat. Voor een taak die met action_ids is aangemaakt, bevat dit ene bestand elke gevraagde actie als een aparte clip.
- 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 (bijv. als de change_fps-bewerking 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
}

GET/openapi/v1/animations/library

Animaties Weergeven

Retourneert elke animatie in de bibliotheek, gesorteerd op action_id. De respons is een volledige lijst in plaats van een pagina, dus één aanroep volstaat om een actiekiezer te vullen. Filters beperken het resultaat; laat ze allemaal weg om alles op te halen.

Om dezelfde catalogus visueel te doorbladeren, met een geanimeerde preview van elke actie, zie de Animatiebibliotheek referentie.

Dit endpoint is gratis — het verbruikt geen credits.

Parameters

Name
search
Type
string
Description
Hoofdletterongevoelige substringovereenkomst op name of key. Wordt letterlijk gematcht, dus % en _ zijn gewone tekens in plaats van jokertekens.
Name
category
Type
string
Description
Exacte overeenkomst op category.
Beschikbare waarden:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Exacte overeenkomst op sub_category. Kan op zichzelf worden gebruikt — namen van subcategorieën zijn niet uniek over categorieën heen (Transitioning komt zowel voor onder Fighting als DailyActions), dus zonder een category matcht het filter die subcategorie waar deze ook voorkomt.
Name
action_ids
Type
string
Description
Kommagescheiden lijst van action_id-waarden om terug te geven, voor het opzoeken van specifieke id's in plaats van bladeren. Accepteert maximaal 200 id's. Id's die geen enkele animatie heeft, zijn simpelweg afwezig in de respons, dus u kunt dit ook gebruiken om te controleren of id's die u heeft opgeslagen nog steeds beschikbaar zijn.

Filters combineren

Filters worden samen toegepast — elk filter beperkt het resultaat verder, dus een animatie wordt alleen geretourneerd als deze aan alle filters voldoet. Binnen één filter matchen meerdere waarden elk ervan: search matcht op name of key, en action_ids matcht op elke id in de lijst.

Dat betekent dat een combinatie zonder overlap een lege array retourneert in plaats van een fout. Actie 92 is "Double Combo Attack", een Fighting-animatie:

?action_ids=92&category=Fighting retourneert actie 92.
?action_ids=92&category=Dancing retourneert [] — het is geen Dancing-animatie.
?action_ids=92&search=walk retourneert [] — de naam komt niet overeen met walk.

Om specifieke animaties op te halen ongeacht hun categorie, geeft u action_ids alleen op.

Retourneert

Retourneert een lijst van The Animation Objects.

Elke action_id die hier wordt geretourneerd, wordt geaccepteerd door Een Animatietaak Maken hierboven, en elke id die daar wordt geaccepteerd, wordt hier geretourneerd. Uitgefaseerde animaties ontbreken in beide. Als u de bibliotheek cachet, ververs deze dan periodiek zodat een uitgefaseerde id niet blijft hangen in uw kiezer.

Request

GET

/openapi/v1/animations/library

curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

Het Animatie-object

Name
action_id
Type
integer
Description
De waarde om als action_id door te geven bij het aanmaken van een animatietaak. Uniek en stabiel, maar niet aaneensluitend — verwijderde animaties laten gaten achter in de nummering, dus ga er nooit van uit dat een reeks id's geldig is.
Name
name
Type
string
Description
Mensleesbaar label, voor weergave. Niet uniek: sommige animaties delen een naam met een andere variant, gebruik dus action_id of key als identiteit.
Name
key
Type
string
Description
Unieke, stabiele slug voor de animatie. Gebruik deze wanneer u een niet-numerieke identificatie nodig heeft om uw eigen opslag op te baseren.
Name
category
Type
string
Description
Groepering op het hoogste niveau, bijv. Fighting.
Name
sub_category
Type
string
Description
Groepering binnen de categorie, bijv. AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL van een geanimeerde GIF met een voorbeeld van de actie, geschikt om rechtstreeks in uw eigen kiezer weer te geven.

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}