lowpoly sera retiré le 30 oct. 2026. Changez de modèle avant ces dates pour éviter les erreurs de requête. Voir toutes les dépréciations

API Animation

Appliquez des Animations à des personnages riggés, et listez les Animations que vous pouvez appliquer.


POST/openapi/v1/animations

Créer une tâche d'Animation

Crée une tâche d'Animation, qui applique une animation à un personnage que vous avez riggé précédemment. L'animation peut être l'une des suivantes :

  • 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)
  • Un clip de mouvement que vous avez généré avec l'API Text to Motion (motion_task_id)

Vous pouvez aussi post-traiter la sortie. La tâche s'exécute en arrière-plan. Pour connaître la durée habituelle d'une tâche, consultez Temps de traitement.

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

Paramètres

  • Name
    rig_task_id
    Type
    string
    Requis
    Description

    L'ID de la tâche de rigging dont le personnage doit être animé, provenant de POST /openapi/v1/rigging. La tâche doit avoir le statut SUCCEEDED.

Envoyez exactement un seul des paramètres action_id, action_ids et motion_task_id.

  • Name
    action_ids
    Type
    array of integers
    Requis
    Description

    Requis sauf si vous envoyez action_id ou motion_task_id. Les ID de 1 à 10 animations prédéfinies à appliquer en une seule fois, sans répétition. Plus de 10 ID, ou un ID répété, renvoie 400. Pour les ID, consultez la référence de la Bibliothèque d'animations.

    Meshy renvoie un fichier avec un clip d'animation par action, ce qui convient à une machine à états dans un moteur de jeu. Meshy facture chaque action de la liste. Consultez Tarification.

    Une liste avec un seul ID fonctionne de la même manière que l'envoi de cet ID en tant que action_id.

  • Name
    motion_task_id
    Type
    string
    Requis
    Description

    Requis sauf si vous envoyez action_id ou action_ids. L'ID d'une tâche Text to Motion dont le clip doit être appliqué à la place d'une action prédéfinie. La tâche doit avoir le statut SUCCEEDED, et le rig doit être un bipède.

    Meshy retargete le clip sur le personnage riggé. Il copie le clip au moment de la création de cette tâche, donc cette tâche n'est pas affectée si la tâche Text to Motion expire par la suite ou si vous la supprimez. Meshy conserve les fichiers d'une tâche Text to Motion pendant 3 jours, veillez donc à appliquer le clip avant cette échéance.

  • Name
    post_process
    Type
    object
    Description

    Post-traitement pour la sortie d'animation. Omettez-le pour obtenir les fichiers d'animation standard.

    Avec motion_task_id, le retargeting peut produire une animation disponible uniquement en GLB. Si vous envoyez post_process et qu'aucun fichier FBX n'est disponible, la tâche échoue avec un task_error, et Meshy rembourse vos crédits. Sans post_process, la tâche réussit, et animation_fbx_url est vide.

S'applique uniquement quand post_process is set
  • Name
    operation_type
    Type
    string
    Description

    L'opération à exécuter. Sans ce paramètre, Meshy ne crée aucun fichier supplémentaire. Une valeur absente de la liste suivante renvoie 400.

    Valeurs disponibles :

    • change_fps : change la fréquence d'images en fps
    • fbx2usdz : convertit l'animation en USDZ
    • extract_armature : extrait l'armature sous forme de fichier FBX
  • Name
    fps
    Type
    integer
    défaut 30
    Description

    La fréquence d'images vers laquelle changer, l'une des valeurs 24, 25, 30 ou 60. S'applique uniquement lorsque operation_type est change_fps. Toute autre valeur renvoie 400.

Retours

Le champ result de la réponse contient l'ID de la nouvelle tâche d'Animation.

Modes d'échec

  • Name
    400 - Bad Request
    Description

    La requête ne peut pas s'exécuter. Le message d'erreur indique le problème détecté. Par exemple :

    • Paramètre manquant : rig_task_id est manquant, ou aucun des paramètres action_id, action_ids et motion_task_id n'a été envoyé.
    • Paramètres en conflit : La requête contient plus d'un des paramètres action_id, action_ids et motion_task_id. N'en envoyez qu'un seul.
    • Tâche de rig invalide : rig_task_id n'est pas un ID de tâche valide, n'est pas une tâche de rigging, ou pointe vers une tâche qui n'a pas réussi.
    • ID d'action invalide : Un action_id, ou une entrée dans action_ids, n'est pas une animation valide.
    • Trop d'actions : action_ids contient plus de 10 ID.
    • Actions en double : action_ids contient plusieurs fois le même ID.
    • 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, et Meshy rejette un rig quadrupède.

    Corrigez la requête, puis renvoyez-la. Consultez Erreurs.

  • Name
    401 - Unauthorized
    Description

    La clé API est manquante ou invalide. Vérifiez l'en-tête Authorization.

  • Name
    402 - Payment Required
    Description

    Par exemple :

    • Crédits insuffisants : Le compte n'a pas assez de crédits pour cette tâche, ou le compte a atteint une limite de crédits. Vérifiez votre solde de crédits, puis réessayez.
    • Plan gratuit : La création d'une tâche nécessite un plan payant. Mettez à niveau votre plan dans vos paramètres d'abonnement, puis réessayez.
  • Name
    403 - Forbidden
    Description

    La tâche rig_task_id est un modèle en bas-relief, que ce point de terminaison ne peut pas animer. Le message est This model type does not support this operation. Riggez un modèle différent.

  • Name
    404 - Not Found
    Description

    Meshy ne trouve pas une tâche ou un fichier requis par la requête. L'un des cas suivants s'applique :

    • Meshy ne trouve pas la tâche rig_task_id parmi vos tâches. Vérifiez l'ID.
    • Meshy a supprimé les fichiers de la tâche rig_task_id après son expires_at. Riggez à nouveau le personnage.
    • Meshy ne trouve pas la tâche motion_task_id. Vérifiez l'ID.
    • Le clip de mouvement a expiré, car Meshy conserve les fichiers d'une tâche Text to Motion pendant 3 jours. Créez une autre tâche Text to Motion.
  • Name
    429 - Too Many Requests
    Description

    Vous avez dépassé votre limite de débit. Attendez, puis réessayez. Consultez Limites de débit.


GET/openapi/v1/animations/:id

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

Retourne une tâche d'Animation à partir de son ID.

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
}

Paramètres

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche provenant de la réponse de création.

Retours

L'objet tâche Animation.


DELETE/openapi/v1/animations/:id

Supprimer une tâche d'Animation

Supprime définitivement une tâche d'Animation, y compris ses modèles et ses données. Vous ne pouvez pas annuler une suppression.

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

Paramètres de chemin

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche à supprimer.

Statut de la tâche

Supprimer une tâche PENDING rembourse les crédits utilisés lors de sa création.

Une tâche IN_PROGRESS ne peut pas être supprimée. La requête renvoie 409 Conflict, et la tâche continue de s'exécuter. Meshy ne rembourse pas une tâche qui a démarré, donc la supprimer vous ferait perdre à la fois les crédits et le résultat. Attendez qu'elle atteigne le statut SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

Supprimer une tâche dans un statut final (SUCCEEDED, FAILED ou CANCELED) ne rembourse pas ses crédits.

Retours

200 OK lorsque la tâche est supprimée, ou 409 Conflict lorsque la tâche est IN_PROGRESS.


GET/openapi/v1/animations

Lister les tâches d'Animation

Renvoie une liste paginée de vos tâches d'Animation, les plus récentes en premier. Pour parcourir la liste, utilisez page_num et page_size.

Les tâches que vous créez via l'API n'apparaissent pas dans My Assets dans l'application web, vous les gérez donc via l'API. Pour retrouver une tâche dont vous n'avez plus l'ID, utilisez ce point de terminaison.

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 une tâche d'Animation en continu

Diffuse les mises à jour d'une tâche d'Animation sous forme d'événements envoyés par le serveur (Server-Sent Events, SSE).

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.
// These examples are shortened. Each event holds the full task object.
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, with the same structure as the 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
}

Paramètres

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche provenant de la réponse de création.

Retours

Un flux d'objets de tâche Animation sous forme d'événements envoyés par le serveur.

Chaque événement contient l'objet de tâche complet, selon la même structure que celle renvoyée par le point de terminaison Get. Tant que la tâche est PENDING ou IN_PROGRESS, ses champs de résultat n'ont pas encore de valeurs.


L'objet de tâche Animation

Un objet de tâche Animation décrit une animation appliquée à un personnage riggé. Il contient le statut, la progression et les fichiers d'animation lorsque la tâche réussit.

Propriétés

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
}
  • Name
    id
    Type
    string
    Description

    L'ID de la tâche. Traitez-le comme une chaîne opaque, et ne vous fiez pas à son format.

  • Name
    type
    Type
    string
    Description

    Le type de tâche, toujours animate.

  • Name
    status
    Type
    string
    Description

    Le statut de la tâche, l'une des valeurs PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.

  • Name
    progress
    Type
    integer
    Description

    La part de la tâche déjà effectuée, en pourcentage. Elle vaut 0 jusqu'à ce que la tâche démarre et 100 lorsqu'elle réussit.

  • Name
    created_at
    Type
    timestamp
    Description

    Heure de création de la tâche, en millisecondes Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Heure de démarrage de la tâche, en millisecondes Unix. Elle vaut 0 jusqu'à ce que la tâche démarre.

  • Name
    finished_at
    Type
    timestamp
    Description

    Heure de fin de la tâche, en millisecondes Unix. Elle vaut 0 jusqu'à ce que la tâche se termine.

  • Name
    expires_at
    Type
    timestamp
    Description

    Heure à laquelle les fichiers résultants de la tâche expirent, en millisecondes Unix.

  • Name
    task_error
    Type
    object
    Description

    Les détails de l'erreur lorsque la tâche échoue. Voir Erreurs.

  • Name
    consumed_credits
    Type
    integer
    Description

    Le nombre de crédits utilisés par la tâche. Présent lorsque le statut est PENDING, IN_PROGRESS ou SUCCEEDED. Il vaut 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.

  • Name
    result
    Type
    object
    Description

    Les URL de téléchargement des fichiers d'animation, lorsque la tâche a le statut SUCCEEDED.

    • Name
      animation_glb_url
      Type
      string
      Description
      L'animation sous forme de fichier GLB. Pour une tâche créée avec action_ids, ce fichier unique contient chaque action demandée sous forme de clip distinct.
    • Name
      animation_fbx_url
      Type
      string
      Description
      L'animation sous forme de fichier FBX. Pour une tâche créée avec action_ids, ce fichier unique contient chaque action demandée sous forme de clip distinct.
    • Name
      processed_usdz_url
      Type
      string
      Description
      L'animation traitée sous forme de fichier USDZ.
    • Name
      processed_armature_fbx_url
      Type
      string
      Description
      L'armature traitée sous forme de fichier FBX.
    • Name
      processed_animation_fps_fbx_url
      Type
      string
      Description
      L'animation à la fréquence d'images modifiée, sous forme de fichier FBX, par exemple lorsque vous avez utilisé l'opération change_fps.
  • Name
    preceding_tasks
    Type
    integer
    Description

    Le nombre de tâches devançant celle-ci dans la file d'attente. Cette valeur n'a de sens que tant que la tâche est PENDING.


GET/openapi/v1/animations/library

Lister les animations

Retourne chaque animation de la bibliothèque, triée par action_id. La réponse est la liste complète, sans pagination, de sorte qu'un seul appel peut remplir un sélecteur d'actions. Les filtres restreignent le résultat. Pour obtenir toutes les animations, omettez-les tous.

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

Cette requête ne coûte aucun crédit.

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

Paramètres

  • Name
    search
    Type
    string
    Description

    Texte à rechercher. Meshy retourne les animations dont le name ou le key contient ce texte, sans tenir compte de la casse. Meshy fait correspondre le texte littéralement, donc % et _ ne sont pas des caractères génériques.

  • Name
    category
    Type
    string
    Description

    La catégorie à lister, en correspondance exacte. Une catégorie inconnue retourne une liste vide.

    Valeurs disponibles :

    • WalkAndRun
    • BodyMovements
    • DailyActions
    • Fighting
    • Dancing
  • Name
    sub_category
    Type
    string
    Description

    La sous-catégorie à lister, en correspondance exacte. Vous pouvez l'envoyer sans category. Les noms de sous-catégories ne sont pas uniques entre les catégories. Par exemple, Transitioning se trouve à la fois sous Fighting et sous DailyActions. Ainsi, sans category, le filtre correspond à la sous-catégorie dans toutes les catégories.

  • Name
    action_ids
    Type
    string
    Description

    Les animations à retourner, sous forme de jusqu'à 200 valeurs action_id séparées par des virgules. Utilisez-le pour rechercher des IDs spécifiques plutôt que de parcourir la liste. Plus de 200 IDs retourne 400.

    La réponse omet un ID qu'aucune animation ne possède. Vous pouvez donc aussi utiliser ce filtre pour vérifier si des IDs que vous avez stockés sont toujours disponibles.

Combinaison des filtres

Meshy applique les filtres ensemble. Chacun restreint le résultat, de sorte que Meshy ne retourne une animation que si elle correspond à tous les filtres. Au sein d'un même filtre, n'importe laquelle de ses valeurs peut correspondre. Par exemple, search correspond à name ou key, et action_ids correspond à n'importe quel ID de la liste.

Ainsi, une combinaison sans chevauchement retourne un tableau vide, pas une erreur. L'action 92 est « Double Combo Attack », une animation Fighting. Par exemple :

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

Pour obtenir des animations spécifiques dans n'importe quelle catégorie, envoyez action_ids seul.

Retours

Une liste d'objets animation.


L'objet animation

Un objet animation décrit une animation dans la bibliothèque.

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"
}
  • Name
    action_id
    Type
    integer
    Description

    La valeur à envoyer comme action_id lorsque vous créez une tâche Animation. Elle est unique et stable, mais pas contiguë. Les animations retirées laissent des trous dans la numérotation, donc ne présumez pas que chaque identifiant d'une plage est valide.

  • Name
    name
    Type
    string
    Description

    Le nom d'affichage de l'animation. Il n'est pas unique, car certaines animations partagent un nom avec une autre variante. Pour identifier une animation, utilisez action_id ou key.

  • Name
    key
    Type
    string
    Description

    Un identifiant 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

    Le groupe de premier niveau, par exemple Fighting.

  • Name
    sub_category
    Type
    string
    Description

    Le groupe au sein de la catégorie, par exemple AttackingwithWeapon.

  • Name
    preview_url
    Type
    string
    Description

    URL d'un aperçu GIF animé de l'action. Vous pouvez l'afficher directement dans votre propre sélecteur.