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.

De taak draait op de achtergrond. Voor een indicatie van de verwerkingstijd, zie Verwerkingstijden.

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 Animatiebibliotheek Referentie voor een volledige lijst met 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 om tegelijk toe te passen, teruggegeven als één enkel bestand dat per actie één animatieclip bevat — 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 Animatiebibliotheek Referentie; 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 opnieuw gerichaamd op 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 blijven 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-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 gebruik van action_ids geeft de taak één samengevoegd bestand terug in plaats van één bestand per actie: animation_glb_url en animation_fbx_url verwijzen elk naar één enkel asset dat elke gevraagde actie als aparte clip bevat.

Clipvolgorde: de volgorde van de action_ids-array, niet de numerieke volgorde van de id's.
Clipnamen: de naam van de animatie in de bibliotheek, overeenkomend met de namen die je krijgt wanneer je alle animaties van een personage als één bestand exporteert vanuit de Meshy web-app. Als twee opgevraagde id's naar dezelfde clipnaam verwijzen, 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 het retargeten resulteren in een animatie 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.

Resultaten

De result-eigenschap van het antwoord 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 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 rigging-taak: De rig_task_id is ongeldig of verwijst naar een mislukte/niet-bestaande taak.
- Ongeldige action-ID: Een action_id — of een item van 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 bij 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 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 opgegeven via rig_task_id is niet gevonden, de motion-taak opgegeven via motion_task_id is niet gevonden, of de motion-clip is verlopen (bron-taak-assets blijven 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

Met deze endpoint kunt u een animatietaak ophalen op basis van een geldige taak-id. Raadpleeg The Animation Task Object om te zien welke eigenschappen zijn opgenomen.

Parameters

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

Returns

Het antwoord bevat het Animation Task-object. Raadpleeg de sectie The Animation Task Object voor meer 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 een animatietaak permanent, inclusief alle bijbehorende modellen en gegevens. Deze actie is onomkeerbaar.

Padparameters

Name
id
Type
path
Description
De ID van de te verwijderen animatietaak.

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 actief. 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 status SUCCEEDED, FAILED of CANCELED bereikt, en verwijder de taak daarna.

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

Retourwaarden

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

List Animation Tasks

Geeft een gepagineerde lijst van de Animatie-taken 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 bij Mijn assets in 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 identifier 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 response-stream 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 karakter.

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
Progress 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 PM GMT wordt bijvoorbeeld 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 met verwerken. 0 als nog niet gestart.
Name
finished_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak is voltooid. 0 als nog 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 task_error-objectreferentie.
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 een 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. Voor een taak die is aangemaakt met action_ids, bevat dit ene bestand elke aangevraagde actie als een afzonderlijke clip.
- Name
  animation_fbx_url
  Type
  string
  Description
  Downloadbare URL voor de animatie in FBX-formaat. Voor een taak die is aangemaakt met action_ids, bevat dit ene bestand elke aangevraagde actie als een afzonderlijke 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 (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
}

GET/openapi/v1/animations/library

List Animations

Geeft elke animatie in de bibliotheek terug, gesorteerd op action_id. De response 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 voorbeeldweergave van elke actie, zie de Animatiebibliotheek-referentie.

Deze endpoint is gratis — hij verbruikt geen credits.

Parameters

Name
search
Type
string
Description
Hoofdletterongevoelige substring-overeenkomst op name of key. Wordt letterlijk vergeleken, 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 onder Fighting als onder DailyActions voor), dus zonder een category komt het filter overeen met 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 ids in plaats van bladeren. Accepteert maximaal 200 ids. Ids die geen enkele animatie draagt, ontbreken eenvoudigweg in de response, dus je kunt dit ook gebruiken om te controleren of ids die je hebt opgeslagen nog 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 komen meerdere waarden overeen met elk ervan: search komt overeen met name of key, en action_ids komt overeen met elke id in de lijst.

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

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

Om specifieke animaties op te halen ongeacht hun categorie, geef je action_ids op zichzelf door.

Retourneert

Geeft een lijst van De Animatie-objecten terug.

Elke action_id die hier wordt geretourneerd, wordt geaccepteerd door Een Animatietaak aanmaken hierboven, en elke id die daar wordt geaccepteerd, wordt hier geretourneerd. Uitgefaseerde animaties ontbreken in beide. Als je de bibliotheek cachet, ververs deze dan periodiek zodat een uitgefaseerde id niet blijft hangen in je 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 die moet worden doorgegeven als action_id bij het aanmaken van een animatietaak. Uniek en stabiel, maar niet aaneensluitend — uitgefaseerde animaties laten gaten achter in de nummering, dus ga er nooit van uit dat een bereik van 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 daarom action_id of key als identiteit.
Name
key
Type
string
Description
Unieke, stabiele slug voor de animatie. Gebruik deze wanneer je een niet-numerieke identifier nodig hebt om je eigen opslag mee te sleutelen.
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 die een voorbeeld van de actie toont, geschikt om direct weer te geven in je eigen keuzemenu.

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"
}