API de Rigging

L'API de Rigging vous permet d'ajouter de manière programmatique un squelette (armature) à des modèles humanoïdes 3D, en liant le maillage à celui-ci afin qu'ils soient prêts pour l'animation. Pour appliquer des animations à un personnage riggé, voir l'API d'Animation.

Veuillez noter que le rigging programmatique fonctionne actuellement bien uniquement avec des assets humanoïdes standard (bipèdes) avec des membres et une structure corporelle clairement définis pour le moment.

POST/openapi/v1/rigging

Créer une tâche de rigging

Ce point de terminaison vous permet de créer une nouvelle tâche de rigging pour un modèle 3D donné. Une fois terminée avec succès, elle fournit un personnage rigué dans des formats standards et, optionnellement, des animations de base de marche/course.

La tâche s'exécute en arrière-plan. Pour connaître la durée habituelle, consultez Durées de traitement.

Actuellement, le rigging automatique n'est pas adapté aux modèles suivants :

Maillages sans texture
Assets non humanoïdes
Assets humanoïdes avec une structure des membres et du corps peu claire

Lors de l'utilisation de input_task_id, les modèles comportant plus de 300 000 faces ne sont pas pris en charge pour le rigging. Veuillez utiliser l'API Remesh pour réduire le nombre de faces avant le rigging.

Lors de l'utilisation de model_url, le visage du personnage doit être orienté vers l'axe +Z (la direction avant standard de glTF). Les modèles orientés vers d'autres axes échoueront à l'estimation de la pose.

Paramètres

Un seul des deux paramètres input_task_id ou model_url est requis. Si les deux sont fournis, input_task_id est prioritaire.

Name
input_task_id
Type
string
Requis
Description
La tâche d'entrée qui doit être riguée. Nous prenons actuellement en charge les modèles humanoïdes texturés.

Name
model_url
Type
string
Requis
Description
Veuillez fournir un modèle 3D que Meshy riguera, via une URL publiquement accessible ou une Data URI. Nous prenons actuellement en charge les fichiers GLB humanoïdes texturés (format .glb).
Taille de fichier maximale : 100 Mo.

Name
height_meters
Type
number
défaut 1.7
Description
La hauteur approximative du modèle de personnage en mètres. Cela aide à la mise à l'échelle et à la précision du rigging. Doit être un nombre positif.
Name
texture_image_url
Type
string
Description
L'image de texture de couleur de base du modèle, dépliée en UV. URL publiquement accessible ou Data URI. Nous prenons actuellement en charge le format .png.
Taille de fichier maximale : 20 Mo.

Retours

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

Modes d'échec

Name
400 - Bad Request
Description
La requête était inacceptable. Causes courantes :
- Paramètre manquant : model_url ou input_task_id doit être fourni.
- Format de modèle invalide : model_url pointe vers un fichier avec une extension non prise en charge (seul .glb est pris en charge).
- URL inaccessible : model_url n'a pas pu être téléchargée.
- Fichier de modèle trop volumineux : le fichier model_url dépasse 100 Mo.
- Image trop volumineuse : l'image texture_image_url dépasse 20 Mo.
- Tâche d'entrée invalide : input_task_id ne fait pas référence à une tâche API valide.
- Nombre de faces dépassé : le modèle d'entrée comporte plus de 300 000 faces. Veuillez utiliser l'API Remesh pour réduire le nombre de faces avant le rigging.
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
422 - Unprocessable Entity
Description
L'estimation de la pose a échoué. Le modèle fourni n'est peut-être pas un personnage humanoïde valide.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

GET/openapi/v1/rigging/:id

Récupérer une tâche de rigging

Ce point de terminaison vous permet de récupérer une tâche de rigging donnée un id de tâche valide. Référez-vous à L'Objet Tâche de Rigging pour voir quelles propriétés sont incluses.

Paramètres

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

Retours

La réponse contient l'objet Tâche de Rigging. Consultez la section L'Objet Tâche de Rigging pour plus de détails.

Requête

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Réponse

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/rigging/:id

Supprimer une tâche de rigging

Ce point de terminaison supprime définitivement une tâche de rigging, y compris tous les modèles et données associés. Cette action est irréversible.

Paramètres de chemin

Name
id
Type
path
Description
L'ID de la tâche de rigging à 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, donc la supprimer en cours d'exécution vous ferait perdre à la fois les crédits et le résultat. Attendez qu'elle atteigne SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.

Une tâche dans un état terminal (SUCCEEDED, FAILED ou CANCELED) est supprimée sans remboursement.

Retourne

Retourne 200 OK en cas de succès, ou 409 Conflict lorsque la tâche est IN_PROGRESS.

Request

DELETE

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/rigging/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 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."
}

GET/openapi/v1/rigging

Lister les tâches de rigging

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

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 trouver une tâche dont vous n'avez plus l'ID.

Request

GET

/openapi/v1/rigging

curl "https://api.meshy.ai/openapi/v1/rigging?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/rigging/:id/stream

Diffuser une tâche de rigging

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

Paramètres

Name
id
Type
path
Description
Identifiant unique pour la tâche de rigging à diffuser.

Retours

Retourne un flux d'Objets de la Tâche de Rigging en tant que Server-Sent Events.

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse inclura uniquement les champs nécessaires progress et status.

Requête

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream 
-H "Authorization: Bearer ${YOUR_API_KEY}"

Flux de Réponse

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Rigging Task Object structure
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  },
  "preceding_tasks": 0
}

L'Objet Tâche de Rigging

L'objet Tâche de Rigging représente l'unité de travail pour le rigging d'un personnage.

Propriétés

Name
id
Type
string
Description
Identifiant unique pour la tâche.
Name
type
Type
string
Description
Type de la tâche de Rigging. La valeur est rig.
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). 0 si non commencée, 100 si réussie.
Name
created_at
Type
timestamp
Description
Horodatage (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, vendredi 1er septembre 2023 à 12:00:00 GMT est représenté par 1693569600000. Cela s'applique à tous les horodatages dans Meshy API.
Name
started_at
Type
timestamp
Description
Horodatage (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 (millisecondes depuis l'époque) lorsque la tâche s'est terminée. 0 si non terminée.
Name
expires_at
Type
timestamp
Description
Horodatage (millisecondes depuis l'époque) lorsque les assets de résultat de la tâche expirent et peuvent être supprimés.
Name
task_error
Type
object
Description
Détails de l'erreur pour les tâches échouées. Voir Erreurs pour la référence complète de l'objet task_error.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par cette tâche. Présent lorsque le statut de la tâche est PENDING, IN_PROGRESS, ou SUCCEEDED. Retourne 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).
Name
result
Type
object
Description
Contient les URLs des assets de sortie si la tâche SUCCEEDED, null sinon.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL téléchargeable pour le personnage riggé au format FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL téléchargeable pour le personnage riggé au format GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Contient les URLs pour les animations par défaut. (par exemple si generate_basic_animations était implicitement vrai ou activé par défaut).
  Name
  walking_glb_url
  Type
  string
  Description
  URL téléchargeable pour l'animation de marche au format GLB (avec skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL téléchargeable pour l'animation de marche au format FBX (avec skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL téléchargeable pour l'armature de l'animation de marche au format GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL téléchargeable pour l'animation de course au format GLB (avec skin).
  Name
  running_fbx_url
  Type
  string
  Description
  URL téléchargeable pour l'animation de course au format FBX (avec skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL téléchargeable pour l'armature de l'animation de course au format GLB.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches précédentes dans la file d'attente. Significatif uniquement si le statut est PENDING.

Exemple d'Objet Tâche de Rigging

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}