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.

Statut de la tâche

Une tâche qui est 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 que le worker a déjà commencé à traiter ne sont pas remboursables ; supprimer la tâche 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 terminal (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/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 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."
}

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
}