API de Rigging

La API de Rigging te permite añadir programáticamente un esqueleto (esqueleto) a modelos humanoides 3D, vinculando la malla a él para que estén listos para la animación. Para aplicar animaciones a un personaje con rigging, consulta la API de Animación.

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 por el 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. Tras completarse correctamente, proporciona un personaje con rigging 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 textura
Assets no humanoides
Assets 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 con rigging. Usa la API de Remallado para reducir el número de caras antes del rigging.

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

Parámetros

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

Name
input_task_id
Type
string
Requerido
Description
La tarea de entrada que necesita rigging. Actualmente admitimos modelos humanoides con textura.

Name
model_url
Type
string
Requerido
Description
Proporciona un modelo 3D para que Meshy le aplique rigging mediante una URL de acceso público o un Data URI. Actualmente admitimos archivos GLB humanoides con textura (formato .glb).

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

Devuelve

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 no fue aceptable. Causas comunes:
- Parámetro faltante: Se debe proporcionar model_url o input_task_id.
- Formato de modelo no válido: model_url apunta a un archivo con una extensión no compatible (solo se admite .glb).
- URL inaccesible: No se pudo descargar model_url.
- Tarea de entrada no válida: input_task_id no hace referencia a una tarea de API válida.
- Número de caras excedido: El modelo de entrada tiene más de 300,000 caras. Usa la API de Remallado para reducir el número de caras antes del rigging.
Name
401 - Unauthorized
Description
Falló la autenticación. Revisa tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
422 - Unprocessable Entity
Description
Falló la estimación de pose. El modelo proporcionado puede no ser un personaje humanoide válido.
Name
429 - Too Many Requests
Description
Has superado 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 se incluyen.

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de rigging que se desea recuperar.

Devoluciones

La respuesta contiene el objeto de tarea de rigging. Consulta la sección El objeto de tarea de rigging para obtener más detalles.

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

Eliminar una tarea de rigging

Este endpoint elimina permanentemente una tarea de rigging, incluidos 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 que se va a eliminar.

Devuelve

Devuelve 200 OK si se realiza correctamente.

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

Transmitir una tarea de rigging

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

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de rigging que se va a transmitir.

Devuelve

Devuelve un flujo de Los objetos de tarea de rigging como Server-Sent Events.

Para tareas PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios 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 de 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
progress de la tarea (0-100). 0 si no ha empezado, 100 si se completó correctamente.
Name
created_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época Unix) 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 Unix) cuando la tarea comenzó a procesarse. 0 si no ha empezado.
Name
finished_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época Unix) cuando la tarea terminó. 0 si no ha terminado.
Name
expires_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época Unix) cuando los assets de resultado de la tarea expiran y pueden eliminarse.
Name
task_error
Type
object
Description
Detalles del error para tareas fallidas. Consulta Errores para ver la referencia completa del objeto task_error.
Name
consumed_credits
Type
integer
Description
El número de créditos consumidos por esta tarea. Está 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 URL de los assets de salida si la tarea tiene el estado SUCCEEDED; de lo contrario, null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL descargable para el personaje con rigging en formato FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL descargable para el personaje con rigging en formato GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Contiene URL para animaciones predeterminadas. (p. ej., si generate_basic_animations era implícitamente verdadero o estaba habilitado de forma predeterminada).
  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 recuento de tareas precedentes en la cola. Solo es significativo 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
}