API Texte vers Mouvement

Générez des clips de mouvements de personnages à partir de descriptions en langage naturel. Décrivez une action — "un personnage qui fait signe de la main", "un zombie avançant en traînant des pieds" — et recevez un clip de mouvement brut que vous pouvez retargeter sur des personnages avec un rig dans votre propre pipeline ou vos outils de création.

La sortie est un clip de mouvement autonome : il ne nécessite pas et n'est pas attaché à un modèle de personnage. Pour riguer un personnage en premier, voir l'API de rigging.

POST/openapi/v1/text-to-motion

Créer une Tâche de Texte à Mouvement

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 la 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. Maximum 400 caractères.
Name
mode
Type
string
défaut prime
Description
Le mode de génération de mouvement. Valeurs disponibles : prime, swift. prime produit la plus haute qualité et sort un FBX ; swift est plus rapide et moins cher, et sort un 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 nouvellement créée de Texte à Mouvement.

Modes d'échec

Name
400 - Bad Request
Description
La demande était inacceptable. Causes communes :
- Prompt manquant ou vide : prompt manquant, vide, ou dépassant 400 caractères.
- Mode invalide : mode n'est ni prime ni swift.
- Durée invalide : duration est manquant, en dehors de 2–10, ou n'est pas un pas de 0.5 secondes.
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 modération de contenu.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

Request

POST

/openapi/v1/text-to-motion

# Générer un clip de mouvement avec seulement les paramètres requis
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
  }'

# Générer un clip rapide et économique en mode Swift
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 de texte à mouvement

Ce point de terminaison vous permet de récupérer une tâche de texte à mouvement en donnant un id de tâche valide. Consultez L'Objet Tâche de Texte à Mouvement pour voir quelles propriétés sont incluses.

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche de texte à mouvement à récupérer.

Retours

La réponse contient l'objet Tâche de Texte à Mouvement. Vérifiez la section L'Objet Tâche de Texte à Mouvement pour plus de détails.

Requête

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

Réponse

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

Liste des Tâches de Texte en Mouvement

Renvoie une liste paginée des tâches de Texte en Mouvement de l'appelant, des plus récentes aux plus anciennes. Pagination standard via page_num et page_size.

La réponse est un tableau d'objets Tâche de Texte en Mouvement.

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

Requête

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

Réponse

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

GET/openapi/v1/text-to-motion/:id/stream

Streamer une tâche Texte à Mouvement

Ce point de terminaison diffuse des mises à jour en temps réel pour une tâche Texte à Mouvement en utilisant les Server-Sent Events (SSE).

Paramètres

Name
id
Type
path
Description
Identifiant unique pour la tâche Texte à Mouvement à diffuser.

Renvoie

Renvoie un flux d'Objets de la Tâche Texte à Mouvement en tant que Server-Sent Events.

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 toujours vides ("" / 0) et finished_at / expires_at sont 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

// Exemple d'événement d'erreur
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Les événements de message transportent l'objet de tâche complet à chaque étape; les champs de résultat
// restent vides jusqu'à ce que la tâche réussisse.
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: { // Exemple d'un élément de flux de tâche réussie, reflétant la structure de l'objet de la tâche Texte à Mouvement
  "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 de Texte à Mouvement

Ce point de terminaison supprime de façon permanente une tâche de Texte à Mouvement, y compris le clip de mouvement généré. Cette action est irréversible.

Paramètres de Chemin

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

Retours

Retourne 200 OK en cas de succès.

Requête

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

Réponse

// Retourne 200 Ok en cas de succès.

L'objet Tâche de Texte à Mouvement

L'objet Tâche de Texte à Mouvement représente l'unité de travail pour générer un clip de mouvement à partir d'un prompt texte.

Propriétés

Name
id
Type
string
Description
Identifiant unique pour 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'époque) lorsque la tâche a été créée.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, suivant la norme RFC 3339. Par exemple, le vendredi 1 septembre 2023 à 12:00:00 PM GMT est représenté comme 1693569600000. Cela s'applique à tous les horodatages dans Meshy API.
Name
started_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'époque) lorsque la tâche a commencé à être traitée. 0 si non commencée.
Name
finished_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'époque) lorsque la tâche s'est terminée. 0 si non terminée.
Name
expires_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'époque) lorsque les assets de résultat de la tâche expirent. 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édant dans la file d'attente. Significatif seulement si le statut est PENDING ; omis quand zéro.
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 des erreurs pour les tâches échouées ; null sauf si la tâche a FAILED. Voir 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 SUCCEEDED ; jusqu'à ce moment, 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.

Exemple d'Objet Tâche de Texte à Mouvement

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