API de Rigging

La API de Rigging te permite agregar programáticamente un esqueleto a modelos humanoides 3D, vinculando la malla a este para que estén listos para la animación. Para aplicar animaciones a un personaje riggeado, consulta la API de Animación.

Por favor, ten en cuenta que el rigging programático actualmente solo funciona bien con assets humanoides estándar (bípedos) con extremidades y estructura corporal claramente definidas en este momento.

POST/openapi/v1/rigging

Crear una Tarea de Rigging

Este endpoint te permite crear una nueva tarea de rigging para un modelo 3D dado. Al completarse con éxito, proporciona un personaje riggeado en formatos estándar y opcionalmente animaciones básicas de caminar/correr.

Actualmente, el auto-rigging no es adecuado para los siguientes modelos:

Mallas sin texturas
Activos no humanoides
Activos humanoides con estructura de extremidades y cuerpo poco clara

Al usar input_task_id, los modelos con más de 300,000 caras no son compatibles para rigging. Por favor, utiliza la API de Remallado para reducir el número de caras antes del rigging.

Al usar model_url, la cara del personaje debe apuntar hacia el eje +Z (la dirección estándar hacia adelante de glTF). Los modelos que miren hacia otros ejes fallarán en la estimación de pose.

Parámetros

Solo uno de input_task_id o model_url es requerido. Si se proporcionan ambos, input_task_id tiene prioridad.

Name
input_task_id
Type
string
Requerido
Description
La tarea de entrada que necesita ser riggeada. Actualmente soportamos modelos humanoides con texturas.

Name
model_url
Type
string
Requerido
Description
Por favor, proporciona un modelo 3D para que Meshy lo riggee a través de una URL públicamente accesible o Data URI. Actualmente soportamos archivos GLB humanoides con texturas (formato .glb).

Name
height_meters
Type
number
predeterminado 1.7
Description
La altura aproximada del modelo del personaje en metros. Esto ayuda en la precisión del escalado y rigging. Debe ser un número positivo.
Name
texture_image_url
Type
string
Description
La imagen de textura de color base del modelo con UV desplegado. URL públicamente accesible o Data URI. Actualmente soportamos formatos .png.

Retornos

La propiedad result de la respuesta contiene el id de la tarea de rigging recién creada.

Modos de Fallo

Name
400 - Bad Request
Description
La solicitud fue inaceptable. Causas comunes:
- Parámetro faltante: Se debe proporcionar model_url o input_task_id.
- Formato de modelo inválido: El model_url apunta a un archivo con una extensión no soportada (solo se soporta .glb).
- URL inalcanzable: No se pudo descargar el model_url.
- Tarea de entrada inválida: El input_task_id no se refiere a una tarea de API válida.
- Exceso de conteo de caras: El modelo de entrada tiene más de 300,000 caras. Por favor, utiliza la API de Remallado para reducir el número de caras antes del rigging.
Name
401 - Unauthorized
Description
La autenticación falló. Por favor, verifica tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
422 - Unprocessable Entity
Description
La estimación de pose falló. El modelo proporcionado puede no ser un personaje humanoide válido.
Name
429 - Too Many Requests
Description
Has excedido tu límite de tasa.

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

Recuperar una Tarea de Rigging

Este endpoint te permite recuperar una tarea de rigging dado un id de tarea válido. Consulta El Objeto de Tarea de Rigging para ver qué propiedades están incluidas.

Parámetros

Name
id
Type
path
Description
Identificador único para la tarea de rigging a recuperar.

Retornos

La respuesta contiene el objeto de Tarea de Rigging. Consulta la sección El Objeto de Tarea de Rigging para más detalles.

Solicitud

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

Respuesta

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

Eliminar una Tarea de Rigging

Este endpoint elimina permanentemente una tarea de rigging, incluyendo todos los modelos y datos asociados. Esta acción es irreversible.

Parámetros de Ruta

Name
id
Type
path
Description
El ID de la tarea de rigging a eliminar.

Retornos

Retorna 200 OK en caso de éxito.

Solicitud

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

Respuesta

// Returns 200 Ok on success.

GET/openapi/v1/rigging

Listar Tareas de Rigging

Devuelve una lista paginada de las tareas de rigging del solicitante, de las más recientes a las más antiguas. Paginación estándar a través de page_num y page_size.

Tenga en cuenta que las tareas creadas a través del API se gestionan a través del API — no aparecen en Mis Assets de la aplicación web. Use este endpoint para encontrar una tarea cuyo ID ya no tenga.

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

Transmitir una Tarea de Rigging

Este endpoint transmite actualizaciones en tiempo real para una tarea de Rigging utilizando Server-Sent Events (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único para la tarea de Rigging a transmitir.

Retornos

Devuelve un flujo de Los Objetos de la Tarea de Rigging como Server-Sent Events.

Para tareas PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios de progress y 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
}

El Objeto de Tarea de Rigging

El objeto de Tarea de Rigging representa la unidad de trabajo para el rigging de un personaje.

Propiedades

Name
id
Type
string
Description
Identificador único para la tarea.
Name
type
Type
string
Description
Tipo de la tarea de Rigging. El valor es rig.
Name
status
Type
string
Description
Estado de la tarea. Valores posibles: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progreso de la tarea (0-100). 0 si no ha comenzado, 100 si ha tenido éxito.
Name
created_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época) cuando se creó la tarea.
Una marca de tiempo representa el número de milisegundos transcurridos desde el 1 de enero de 1970 UTC, siguiendo el estándar RFC 3339. Por ejemplo, el viernes 1 de septiembre de 2023 a las 12:00:00 PM GMT se representa como 1693569600000. Esto se aplica a todas las marcas de tiempo en Meshy API.
Name
started_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época) cuando la tarea comenzó a procesarse. 0 si no ha comenzado.
Name
finished_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época) cuando la tarea terminó. 0 si no ha terminado.
Name
expires_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época) cuando los assets de resultado de la tarea expiran y pueden ser eliminados.
Name
task_error
Type
object
Description
Detalles del error para tareas fallidas. Consulte Errores para la referencia completa del objeto task_error.
Name
consumed_credits
Type
integer
Description
El número de créditos consumidos por esta tarea. Presente cuando el estado de la tarea es PENDING, IN_PROGRESS o SUCCEEDED. Devuelve 0 para tareas FAILED (los créditos se reembolsan en caso de fallo).
Name
result
Type
object
Description
Contiene las URLs de los assets de salida si la tarea SUCCEEDED, null de lo contrario.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL descargable para el personaje rigged en formato FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL descargable para el personaje rigged en formato GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Contiene URLs para animaciones predeterminadas. (por ejemplo, si generate_basic_animations era implícitamente verdadero o habilitado por defecto).
  Name
  walking_glb_url
  Type
  string
  Description
  URL descargable para la animación de caminar en formato GLB (con piel).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL descargable para la animación de caminar en formato FBX (con piel).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL descargable para el esqueleto de la animación de caminar en formato GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL descargable para la animación de correr en formato GLB (con piel).
  Name
  running_fbx_url
  Type
  string
  Description
  URL descargable para la animación de correr en formato FBX (con piel).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL descargable para el esqueleto de la animación de correr en formato GLB.
Name
preceding_tasks
Type
integer
Description
El conteo de tareas precedentes en la cola. Significativo solo si el estado es 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
}