API Text to Motion

Générez des clips d'animation de personnage à partir de descriptions en langage naturel. Décrivez une action — « un personnage qui salue de la main », « un zombie qui avance en traînant les pieds » — et obtenez un clip de mouvement brut que vous pouvez retargeter sur des personnages riggés dans votre propre pipeline ou vos outils DCC.

Le résultat est un clip de mouvement autonome : il ne nécessite pas de modèle de personnage et n'y est pas rattaché. Pour effectuer d'abord le rigging d'un personnage, consultez l'API Rigging. Pour appliquer un clip généré à votre personnage riggé, transmettez l'id de la tâche en tant que motion_task_id à l'API Animation — appliquez-le dans la fenêtre de conservation des ressources de 3 jours.

POST/openapi/v1/text-to-motion

Créer une tâche Text to Motion

Ce point de terminaison crée une nouvelle tâche pour générer un clip de mouvement à partir d'un prompt textuel.

Une tâche avec le mode prime coûte 10 crédits et génère avec notre modèle de mouvement de plus haute qualité. Une tâche avec le mode swift coûte 3 crédits et génère plus rapidement avec notre modèle de mouvement économique.

Paramètres

  • Name
    prompt
    Type
    string
    Requis
    Description

    Une description en langage naturel du mouvement à générer. 400 caractères maximum.

  • Name
    mode
    Type
    string
    défaut prime
    Description

    Le mode de génération de mouvement. Valeurs disponibles : prime, swift. prime produit la meilleure qualité et génère du FBX ; swift est plus rapide et moins coûteux et génère du BVH.

  • Name
    duration
    Type
    number
    Requis
    Description

    La durée cible du clip de mouvement en secondes. Entre 2 et 10, par pas de 0.5 (par exemple 2, 2.5, 3, … 10).

Retours

La propriété result de la réponse contient l'id de la tâche Text to Motion nouvellement créée.

Modes d'échec

  • Name
    400 - Bad Request
    Description

    La requête était inacceptable. Causes courantes :

    • Prompt manquant ou vide : prompt est manquant, vide, ou dépasse 400 caractères.
    • Mode invalide : mode n'est ni prime ni swift.
    • Durée invalide : duration est manquante, hors de la plage 2–10, ou n'est pas un multiple de 0.5 seconde.
  • 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
    403 - Forbidden
    Description

    Le prompt a été signalé par la moderation de contenu.

  • Name
    429 - Too Many Requests
    Description

    Vous avez dépassé votre limite de débit.

Request

POST
/openapi/v1/text-to-motion
# Generate a motion clip with required params only
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "duration": 3
  }'

# Generate a fast, economical clip with Swift mode
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "mode": "swift",
    "duration": 4.5
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}
GET/openapi/v1/text-to-motion/:id

Récupérer une tâche Text to Motion

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

Paramètres

  • Name
    id
    Type
    path
    Description

    Identifiant unique de la tâche Text to Motion à récupérer.

Retours

La réponse contient l'objet tâche Text to Motion. Consultez la section L'objet tâche Text to Motion pour plus de détails.

Request

GET
/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791
curl https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}
GET/openapi/v1/text-to-motion

Lister les tâches Text to Motion

Renvoie une liste paginée des tâches Text to Motion de l'appelant, les plus récentes en premier. Pagination standard via page_num et page_size.

La réponse est un tableau d'objets Text to Motion Task.

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/text-to-motion
curl "https://api.meshy.ai/openapi/v1/text-to-motion?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]
GET/openapi/v1/text-to-motion/:id/stream

Diffuser en flux une tâche de Text to Motion

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

Paramètres

  • Name
    id
    Type
    path
    Description

    Identifiant unique de la tâche de Text to Motion à diffuser.

Retours

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

Chaque événement message transporte l'objet de tâche complet. Tant que la tâche est en PENDING ou IN_PROGRESS, les champs result sont encore vides ("" / 0) et finished_at / expires_at valent 0 ; surveillez status et progress.

Request

GET
/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream
curl -N https://api.meshy.ai/openapi/v1/text-to-motion/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 events carry the full task object at every stage; the result
// fields stay empty until the task succeeds.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "IN_PROGRESS",
  "progress": 50,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 0,
  "expires_at": 0,
  "task_error": null,
  "result": {
    "motion_url": "",
    "motion_format": "",
    "duration_ms": 0,
    "mode": ""
  },
  "consumed_credits": 10
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Text to Motion Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}
DELETE/openapi/v1/text-to-motion/:id

Supprimer une tâche Text to Motion

Ce point de terminaison supprime définitivement une tâche Text to Motion, y compris le clip d'animation généré. Cette action est irréversible.

Paramètres de chemin

  • Name
    id
    Type
    path
    Description

    L'ID de la tâche Text to Motion à supprimer.

Retours

Retourne 200 OK en cas de succès.

Request

DELETE
/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

L'objet Text to Motion Task

L'objet Text to Motion Task représente l'unité de travail pour générer un clip de mouvement à partir d'un prompt textuel.

Propriétés

  • Name
    id
    Type
    string
    Description

    Identifiant unique de la tâche.

  • Name
    type
    Type
    string
    Description

    Type de la tâche. La valeur est text-to-motion.

  • 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 1 septembre 2023 à 12h00 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 démarré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ésultants de la tâche. 0 jusqu'à ce que la tâche se termine. Le clip généré est conservé pendant 3 jours après la fin de la tâche ; téléchargez-le avant son expiration.

  • 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 ; omis lorsqu'il est nul.

  • Name
    consumed_credits
    Type
    integer
    Description

    Le nombre de crédits consommés par cette tâche. 10 pour le mode prime, 3 pour le mode swift. Retourne 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).

  • Name
    task_error
    Type
    object
    Description

    Détails de l'erreur pour les tâches échouées ; null sauf si la tâche a échoué (FAILED). Consultez Erreurs pour la référence complète de l'objet task_error.

  • Name
    result
    Type
    object
    Description

    Contient le clip de mouvement généré une fois que la tâche a réussi (SUCCEEDED) ; jusque-là, les champs sont présents mais vides ("" / 0).

    • Name
      motion_url
      Type
      string
      Description
      URL téléchargeable pour le clip de mouvement généré. L'URL est re-signée à chaque lecture et expire avec la fenêtre de rétention de la tâche.
    • Name
      motion_format
      Type
      string
      Description
      Format de fichier du clip : fbx pour le mode prime, bvh pour le mode swift.
    • Name
      duration_ms
      Type
      integer
      Description
      Durée du clip généré en millisecondes.
    • Name
      mode
      Type
      string
      Description
      Le mode avec lequel le clip a été généré : prime ou swift.

Example Text to Motion Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}