API Animation

Endpoints permettant de découvrir les animations disponibles et de les appliquer à des personnages riggés.

POST/openapi/v1/animations

Créer une tâche d'animation

Ce point de terminaison vous permet de créer une nouvelle tâche pour appliquer une animation à un personnage préalablement riggé — une action prédéfinie issue de la bibliothèque d'animations (action_id), plusieurs actions prédéfinies fusionnées en un seul fichier (action_ids), ou un clip de mouvement que vous avez généré avec l'API Text to Motion (motion_task_id). Inclut des options de post-traitement.

Paramètres

Name
rig_task_id
Type
string
Requis
Description
L'id d'une tâche de rigging terminée avec succès (issue de POST /openapi/v1/rigging). Le personnage de cette tâche sera animé.
Name
action_id
Type
integer
Description
L'identifiant de l'action d'animation prédéfinie à appliquer. Consultez la référence de la bibliothèque d'animations pour la liste complète des animations disponibles. Fournissez exactement un seul des paramètres action_id, action_ids ou motion_task_id.
Name
action_ids
Type
array of integers
Description
Plusieurs actions d'animation prédéfinies à appliquer en une seule fois, renvoyées sous forme d'un fichier unique contenant un clip d'animation par action — utile pour piloter un personnage depuis une machine à états dans un moteur de jeu. Fournissez de 1 à 10 valeurs action_id issues de la référence de la bibliothèque d'animations ; les identifiants doivent être uniques. Coûte 3 crédits par action. Fournissez exactement un seul des paramètres action_id, action_ids ou motion_task_id.
Passer un action_ids à un seul élément équivaut à passer cette valeur en tant que action_id.
Name
motion_task_id
Type
string
Description
L'id d'une tâche Text to Motion terminée avec succès à appliquer à la place d'une action prédéfinie. Le clip généré est reciblé sur le personnage riggé et le clip est figé au moment de la création, de sorte que cette tâche n'est pas affectée si la tâche source expire ou est supprimée par la suite. Les assets de la tâche source sont conservés pendant 3 jours — appliquez le clip avant son expiration. Nécessite un rig bipède. Fournissez exactement un seul des paramètres action_id, action_ids ou motion_task_id.
Name
post_process
Type
object
Description
Post-traitement facultatif pour la sortie d'animation. Omettez-le pour recevoir les fichiers d'animation standard.

S'applique uniquement quand post_process is set

Name
operation_type
Type
string
Requis
Description
Le type d'opération à effectuer. Valeurs disponibles : change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
défaut 30
Description
La fréquence d'images cible. Applicable uniquement lorsque operation_type vaut change_fps. Valeurs autorisées : 24, 25, 30, 60.

Avec action_ids, la tâche renvoie un fichier fusionné unique plutôt qu'un fichier par action : animation_glb_url et animation_fbx_url pointent chacun vers un unique asset contenant toutes les actions demandées sous forme de clips distincts.

Ordre des clips : l'ordre du tableau action_ids, et non l'ordre numérique des identifiants.
Noms des clips : le nom de l'animation dans la bibliothèque, correspondant aux noms obtenus lors de l'exportation de toutes les animations d'un personnage en un seul fichier depuis l'application web Meshy. Si deux identifiants demandés correspondent au même nom de clip, le second se voit ajouter en suffixe son action_id afin de garder des noms uniques.
Post-traitement : appliqué au fichier fusionné, et non aux clips individuels.

Avec motion_task_id, le recentrage peut produire une animation uniquement au format GLB. Si vous avez demandé un post_process et qu'aucun FBX n'est disponible, la tâche échoue avec une task_error et vos crédits sont automatiquement remboursés ; sans post_process, la tâche réussit et animation_fbx_url est vide.

Retourne

La propriété result de la réponse contient l'id de la tâche de la tâche d'animation nouvellement créée.

Modes d'échec

Name
400 - Bad Request
Description
La requête était inacceptable. Causes courantes :
- Paramètre manquant : rig_task_id est manquant, ou aucun des paramètres action_id, action_ids et motion_task_id n'a été fourni.
- Paramètres en conflit : plus d'un des paramètres action_id, action_ids et motion_task_id a été fourni — ils sont mutuellement exclusifs.
- Tâche de rigging invalide : rig_task_id est invalide ou fait référence à une tâche ayant échoué ou inexistante.
- ID d'action invalide : un action_id — ou une entrée de action_ids — ne correspond à aucune animation valide.
- Trop d'actions : action_ids contient plus de 10 identifiants.
- Actions dupliquées : action_ids contient plusieurs fois le même identifiant.
- Tâche de mouvement non prête : la tâche motion_task_id n'a pas encore atteint le statut SUCCEEDED.
- Rig non pris en charge : motion_task_id nécessite un rig bipède ; les rigs quadrupèdes sont rejetés.
Name
401 - Unauthorized
Description
L'authentification a échoué. Veuillez vérifier votre clé API.
Name
402 - Payment Required
Description
Crédits insuffisants pour effectuer cette tâche.
Name
404 - Not Found
Description
La tâche de rigging spécifiée par rig_task_id est introuvable, la tâche de mouvement spécifiée par motion_task_id est introuvable, ou le clip de mouvement a expiré (les assets de la tâche source sont conservés pendant 3 jours).
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

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

Récupérer une tâche d'Animation

Ce point de terminaison vous permet de récupérer une tâche d'animation à partir d'un id de tâche valide. Consultez L'objet tâche d'animation pour voir les propriétés incluses.

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche d'animation à récupérer.

Retours

La réponse contient l'objet Animation Task. Consultez la section L'objet tâche d'animation pour plus de détails.

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

Supprimer une tâche d'Animation

Ce point de terminaison supprime définitivement une tâche d'animation, y compris tous les modèles et données associés. Cette action est irréversible.

Paramètres de chemin

Name
id
Type
path
Description
L'ID de la tâche d'animation à supprimer.

Statut de la tâche

Une tâche encore PENDING est supprimée et les crédits consommés au moment de la création sont remboursés.

Une tâche déjà IN_PROGRESS ne peut pas être supprimée : la requête est rejetée avec 409 Conflict et la tâche continue de s'exécuter. Les crédits d'une tâche déjà démarrée par le worker ne sont pas remboursables, donc la supprimer en cours d'exécution vous ferait perdre à la fois les crédits et le résultat. Attendez qu'elle atteigne l'état SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

Une tâche dans un état final (SUCCEEDED, FAILED ou CANCELED) est supprimée sans remboursement.

Retours

Retourne 200 OK en cas de succès, ou 409 Conflict lorsque la tâche est IN_PROGRESS.

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

Retourne une liste paginée des tâches d'Animation de l'appelant, les plus récentes en premier. Pagination standard via page_num et page_size.

Notez que les tâches créées via l'API sont gérées via l'API — elles n'apparaissent pas dans « Mes Assets » de l'application web. Utilisez ce point de terminaison pour retrouver une tâche dont vous n'avez plus l'ID.

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

Diffuser en continu une tâche d'Animation

Ce point de terminaison diffuse en continu les mises à jour en temps réel d'une tâche d'Animation à l'aide de Server-Sent Events (SSE).

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche d'Animation à diffuser en continu.

Retourne

Retourne un flux d'objets de tâche d'Animation sous forme de Server-Sent Events.

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse n'inclura que les champs progress et status nécessaires.

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
}

L'objet Animation Task

L'objet Animation Task représente l'unité de travail consistant à appliquer une animation à un personnage riggé.

Propriétés

Name
id
Type
string
Description
Identifiant unique de la tâche.
Name
type
Type
string
Description
Type de la tâche Animation. La valeur est animate.
Name
status
Type
string
Description
Statut de la tâche. Valeurs possibles : PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progression de la tâche (0-100).
Name
created_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'epoch) de la création de la tâche.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, conformément à la norme RFC 3339. Par exemple, le vendredi 1er septembre 2023 à 12:00:00 PM GMT est représenté par 1693569600000. Cela s'applique à tous les horodatages de Meshy API.
Name
started_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'epoch) du début du traitement de la tâche. 0 si non commencée.
Name
finished_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'epoch) de la fin de la tâche. 0 si non terminée.
Name
expires_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'epoch) de l'expiration des assets résultant de la tâche.
Name
task_error
Type
object
Description
Détails de l'erreur pour les tâches ayant échoué. Voir Erreurs pour la référence complète de l'objet task_error.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par cette tâche. Présent lorsque le statut de la tâche est PENDING, IN_PROGRESS, ou SUCCEEDED. Retourne 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).
Name
result
Type
object
Description
Contient les URL des animations de sortie si la tâche a SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL de téléchargement de l'animation au format GLB. Pour une tâche créée avec action_ids, ce fichier unique contient chaque action demandée sous forme de clip séparé.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL de téléchargement de l'animation au format FBX. Pour une tâche créée avec action_ids, ce fichier unique contient chaque action demandée sous forme de clip séparé.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL de téléchargement de l'animation traitée au format USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL de téléchargement de l'armature traitée au format FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL de téléchargement de l'animation avec un FPS modifié au format FBX (par exemple, si l'opération change_fps a été utilisée).
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches précédentes dans la file d'attente. Pertinent uniquement si le statut est 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
}

GET/openapi/v1/animations/library

Lister les animations

Renvoie chaque animation de la bibliothèque, triée par action_id. La réponse est une liste complète plutôt qu'une page, un seul appel suffit donc pour alimenter un sélecteur d'actions. Les filtres restreignent le résultat ; omettez-les tous pour tout récupérer.

Pour parcourir visuellement le même catalogue, avec un aperçu animé de chaque action, consultez la référence de la Bibliothèque d'animations.

Ce point de terminaison est gratuit — il ne consomme aucun crédit.

Paramètres

Name
search
Type
string
Description
Correspondance de sous-chaîne insensible à la casse sur name ou key. La correspondance est littérale, donc % et _ sont des caractères ordinaires et non des jokers.
Name
category
Type
string
Description
Correspondance exacte sur category.
Valeurs disponibles :
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Correspondance exacte sur sub_category. Accepté seul — les noms de sous-catégories ne sont pas uniques d'une catégorie à l'autre (Transitioning apparaît à la fois sous Fighting et sous DailyActions), donc sans category le filtre correspond à cette sous-catégorie partout où elle apparaît.
Name
action_ids
Type
string
Description
Liste de valeurs action_id séparées par des virgules à renvoyer, pour résoudre des identifiants spécifiques plutôt que parcourir la liste. Accepte au maximum 200 identifiants. Les identifiants qu'aucune animation ne porte sont simplement absents de la réponse, ce qui permet aussi de vérifier si des identifiants que vous avez stockés sont toujours disponibles.

Combinaison des filtres

Les filtres sont appliqués ensemble — chacun restreint davantage le résultat, une animation n'est donc renvoyée que si elle les satisfait tous. Au sein d'un même filtre, plusieurs valeurs correspondent si l'une d'elles est satisfaite : search correspond à name ou key, et action_ids correspond à n'importe quel identifiant de la liste.

Cela signifie qu'une combinaison sans chevauchement renvoie un tableau vide plutôt qu'une erreur. L'action 92 est « Double Combo Attack », une animation Fighting :

?action_ids=92&category=Fighting renvoie l'action 92.
?action_ids=92&category=Dancing renvoie [] — ce n'est pas une animation Dancing.
?action_ids=92&search=walk renvoie [] — son nom ne correspond pas à walk.

Pour récupérer des animations spécifiques indépendamment de leur catégorie, passez action_ids seul.

Retours

Renvoie une liste d'Objets Animation.

Chaque action_id renvoyé ici est accepté par Créer une tâche d'animation ci-dessus, et chaque identifiant qu'elle accepte est renvoyé ici. Les animations retirées sont absentes des deux. Si vous mettez la bibliothèque en cache, actualisez-la périodiquement afin qu'un identifiant retiré ne persiste pas dans votre sélecteur.

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

The Animation Object

Name
action_id
Type
integer
Description
La valeur à transmettre en tant que action_id lors de la création d'une tâche d'animation. Unique et stable, mais non contiguë — les animations retirées laissent des trous dans la numérotation, donc ne présumez jamais qu'une plage d'ids est valide.
Name
name
Type
string
Description
Libellé lisible par un humain, destiné à l'affichage. Non unique : certaines animations partagent un nom avec une variante différente, utilisez donc action_id ou key comme identité.
Name
key
Type
string
Description
Slug unique et stable pour l'animation. Utilisez-le lorsque vous avez besoin d'un identifiant non numérique pour indexer votre propre stockage.
Name
category
Type
string
Description
Regroupement de premier niveau, par exemple Fighting.
Name
sub_category
Type
string
Description
Regroupement au sein de la catégorie, par exemple AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL d'un GIF animé prévisualisant l'action, adapté pour un rendu direct dans votre propre sélecteur.

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