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 riggé dans des formats standards et éventuellement des animations de marche/course de base.

Actuellement, l'auto-rigging n'est pas adapté pour les modèles suivants :

Maillages non texturés
Assets non humanoïdes
Assets humanoïdes avec une structure de membres et de corps peu claire

Lors de l'utilisation de input_task_id, les modèles avec plus de 300 000 faces ne sont pas pris en charge pour le rigging. Veuillez utiliser l'API de Remaillage 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 glTF). Les modèles orientés vers d'autres axes échoueront à l'estimation de pose.

Paramètres

Un seul de input_task_id ou model_url est requis. Si les deux sont fournis, input_task_id prend la priorité.

Name
input_task_id
Type
string
Requis
Description
La tâche d'entrée qui doit être riggé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 pour que Meshy puisse le rigguer via une URL accessible publiquement ou un Data URI. Nous prenons actuellement en charge les fichiers GLB humanoïdes texturés (format .glb).

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

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 : Soit model_url soit input_task_id doit être fourni.
- Format de modèle invalide : Le model_url pointe vers un fichier avec une extension non prise en charge (seul .glb est pris en charge).
- URL inaccessible : Le model_url n'a pas pu être téléchargé.
- Tâche d'entrée invalide : Le input_task_id ne se réfère pas à une tâche API valide.
- Nombre de faces dépassé : Le modèle d'entrée a plus de 300 000 faces. Veuillez utiliser l'API de Remaillage 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 pose a échoué. Le modèle fourni peut ne pas être un personnage humanoïde valide.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

Requête

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

Réponse

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

Retours

Retourne 200 OK en cas de succès.

Requête

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

Réponse

// Returns 200 Ok on success.

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
}