API de rigging

L’API de rigging vous permet d’ajouter par programmation un squelette (armature) à des modèles humanoïdes 3D, en y liant le maillage afin qu’ils soient prêts pour l’animation. Pour appliquer des animations à un personnage riggé, consultez l’API Animation.

Veuillez noter que le rigging programmatique fonctionne actuellement correctement uniquement avec des assets humanoïdes standard (bipèdes) dotés de membres et d’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 l’opération terminée avec succès, il fournit un personnage riggé dans des formats standard et, éventuellement, des animations de marche/course de base.

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

Maillages sans texture
Assets non humanoïdes
Assets humanoïdes dont la structure des membres et du corps n’est pas 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 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 de glTF). Les modèles orientés vers d’autres axes échoueront à l’estimation de pose.

Paramètres

Seul l’un des deux paramètres input_task_id ou model_url est obligatoire. 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 riggée. Nous prenons actuellement en charge les modèles humanoïdes avec texture.

Name
model_url
Type
string
Requis
Description
Veuillez fournir un modèle 3D à rigger par Meshy via une URL accessible publiquement ou une Data URI. Nous prenons actuellement en charge les fichiers GLB de modèles humanoïdes avec texture (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 à améliorer la précision de la mise à l’échelle et du rigging. Elle 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 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 de défaillance

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.
- 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 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 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 à partir d’un id valide. Consultez L’objet Tâche de rigging pour voir quelles propriétés sont incluses.

Paramètres

Name
id
Type
path
Description
Identifiant unique de 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.

Request

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

Response

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

Renvoie 200 OK en cas de succès.

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

// Returns 200 Ok on success.

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 à l’aide de Server-Sent Events (SSE).

Paramètres

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

Retours

Renvoie un flux d’objets de tâche de rigging sous forme de Server-Sent Events.

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

Request

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

Response Stream

// 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 de tâche de rigging

L’objet de 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 de 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 elle n’a pas démarré, 100 si elle a réussi.
Name
created_at
Type
timestamp
Description
Horodatage (millisecondes depuis l’époque Unix) 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, 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 Unix) du début du traitement de la tâche. 0 si elle n’a pas démarré.
Name
finished_at
Type
timestamp
Description
Horodatage (millisecondes depuis l’époque Unix) de la fin de la tâche. 0 si elle n’est pas terminée.
Name
expires_at
Type
timestamp
Description
Horodatage (millisecondes depuis l’époque Unix) auquel 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. Consultez 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. Renvoie 0 pour les tâches FAILED (les crédits sont remboursés en cas d’échec).
Name
result
Type
object
Description
Contient les URL des assets de sortie si la tâche a SUCCEEDED, null sinon.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL téléchargeable du personnage riggé au format FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL téléchargeable du personnage riggé au format GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Contient les URL des animations par défaut. (par exemple si generate_basic_animations était implicitement true ou activé par défaut).
  Name
  walking_glb_url
  Type
  string
  Description
  URL téléchargeable de l’animation de marche au format GLB (avec peau).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL téléchargeable de l’animation de marche au format FBX (avec peau).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL téléchargeable de l’armature de l’animation de marche au format GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL téléchargeable de l’animation de course au format GLB (avec peau).
  Name
  running_fbx_url
  Type
  string
  Description
  URL téléchargeable de l’animation de course au format FBX (avec peau).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL téléchargeable de 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. Pertinent uniquement si le statut est PENDING.

Example Rigging Task Object

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