API Texte vers mouvement

Générez des clips d'animation de personnage à partir de descriptions textuelles. Décrivez une action, comme « un personnage qui fait signe de la main » ou « un zombie qui avance en traînant les pieds », et obtenez un clip de mouvement brut. Vous pouvez retargeter le clip 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'est rattaché à aucun. Pour rigger un personnage au préalable, consultez l'API de Rigging. Pour appliquer un clip à votre personnage riggé, envoyez l'id de la tâche en tant que motion_task_id à l'API Animation.

POST/openapi/v1/text-to-motion

Créer une tâche Text to Motion

Crée une tâche Text to Motion, qui génère un clip d'animation à partir d'un prompt textuel.

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.

Une tâche prime coûte 10 crédits et utilise le modèle d'animation de meilleure qualité de Meshy. Une tâche swift coûte 3 crédits et utilise un modèle d'animation plus rapide et moins coûteux.

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

Paramètres

Name
prompt
Type
string
Requis
Description
Texte décrivant l'animation à générer, jusqu'à 400 caractères. Un texte plus long renvoie 400.
Name
mode
Type
string
défaut prime
Description
Le modèle d'animation, qui détermine également le format de fichier du clip.
Valeurs disponibles :
- prime : meilleure qualité, renvoie un clip FBX
- swift : plus rapide et moins cher, renvoie un clip BVH
Toute autre valeur renvoie 400.
Name
duration
Type
number
Requis
Description
La durée cible du clip en secondes, de 2 à 10 par pas de 0.5, par exemple 2, 2.5 ou 3. Toute autre valeur renvoie 400.

Retours

Le champ result de la réponse contient l'ID de la nouvelle tâche Text to Motion.

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 rencontré. Par exemple :
- 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 manquant, hors de la plage 2 à 10, ou ne correspond pas à un pas de 0.5 seconde.
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 ne dispose pas de suffisamment 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.
- Forfait gratuit : la création d'une tâche nécessite un forfait payant. Mettez à niveau votre forfait dans vos paramètres d'abonnement, puis réessayez.
Name
403 - Forbidden
Description
La modération de contenu a signalé le prompt. Modifiez le prompt, puis renvoyez la requête.
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/text-to-motion/:id

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

Renvoie une tâche Text to Motion à partir de son ID.

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
}

Paramètres

Name
id
Type
path
Description
L'ID de la tâche provenant de la réponse de création.

Retour

L'objet tâche Text to Motion.

GET/openapi/v1/text-to-motion

Lister les tâches Text to Motion

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

La réponse est un tableau d'objets de tâche Text to Motion.

Les tâches que vous créez avec l'API restent dans l'API et n'apparaissent pas dans Mes Assets dans l'application web. Pour retrouver une tâche dont vous n'avez plus l'ID, utilisez ce point de terminaison.

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 un tâche Text to Motion

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

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 event, with the same fields as the 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
}

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 Text to Motion sous forme d'événements envoyés par le serveur.

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

DELETE/openapi/v1/text-to-motion/:id

Supprimer une tâche Text to Motion

Supprime définitivement une tâche Text to Motion, y compris son clip d'animation. Une suppression est irréversible.

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

// 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.

L'objet de tâche Text to Motion

Un objet de tâche Text to Motion décrit la génération d'un clip d'animation. Il contient le statut, la progression et le clip lorsque la tâche réussit.

Propriétés

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
}

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 text-to-motion.
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, sous forme de pourcentage de 0 à 100.
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 tant que la tâche n'a pas démarré.
Name
finished_at
Type
timestamp
Description
Heure de fin de la tâche, en millisecondes Unix. Elle vaut 0 tant que la tâche n'est pas terminée.
Name
expires_at
Type
timestamp
Description
Heure d'expiration des fichiers de résultat de la tâche, en millisecondes Unix. Elle vaut 0 tant que la tâche n'est pas terminée. Meshy conserve le clip pendant 3 jours après la fin de la tâche, téléchargez-le donc avant cette échéance.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches qui précèdent celle-ci dans la file d'attente. Cette valeur n'a de sens que tant que la tâche est PENDING. Le champ est omis lorsque la valeur est 0.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par la tâche, 10 pour le mode prime ou 3 pour le mode swift. Il vaut 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.
Name
task_error
Type
object
Description
Les détails de l'erreur lorsque la tâche échoue, et null sinon. Voir Erreurs.
Name
result
Type
object
Description
Le clip d'animation généré lorsque la tâche réussit. Jusque-là, les champs sont présents mais vides ("" ou 0).
- Name
  motion_url
  Type
  string
  Description
  URL de téléchargement du clip d'animation. Meshy signe à nouveau l'URL à chaque lecture, et elle expire avec la fenêtre de rétention de la tâche.
- Name
  motion_format
  Type
  string
  Description
  Le format de fichier du clip, fbx pour le mode prime ou bvh pour le mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  La durée du clip, en millisecondes.
- Name
  mode
  Type
  string
  Description
  Le mode utilisé par Meshy pour générer le clip, prime ou swift.