API de Rigging

Añade un esqueleto a un modelo 3D humanoide y vincula la malla a él, de modo que el personaje esté listo para animar. Para aplicar animaciones a un personaje con rigging, consulta la API de Animación.

El rigging funciona bien solo con personajes humanoides (bípedos) estándar que tengan una estructura de extremidades y cuerpo claramente definida.

POST/openapi/v1/rigging

Crear una tarea de Rigging

Crea una tarea de Rigging para un modelo 3D. Cuando la tarea tiene éxito, devuelve un personaje con rig en formatos estándar y, opcionalmente, animaciones básicas de caminar y correr.

La tarea se ejecuta en segundo plano. Para saber cuánto suele tardar una tarea, consulta Tiempos de procesamiento.

El rigging no es adecuado para estos modelos:

Mallas sin textura
Assets no humanoides
Assets humanoides con una estructura de extremidades y cuerpo poco clara

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

Parámetros

Name
input_task_id
Type
string
Requerido
Description
Obligatorio a menos que envíes model_url. El ID de la tarea cuyo modelo quieres usar para el rigging. Meshy admite modelos humanoides con textura.
El modelo puede tener como máximo 380,000 triángulos (un cuadrilátero cuenta como 2), y un modelo con más devuelve 400. Para mantenerte por debajo del límite, ejecuta primero la API de Remallado con un target_polycount de 300000 o menos, o 150000 o menos con topology: quad.

Name
model_url
Type
string
Requerido
Description
Obligatorio a menos que envíes input_task_id. El modelo para el rigging, como una URL pública o un Data URI. Si envías ambos, Meshy usa input_task_id.
El modelo debe ser un archivo GLB (.glb) de como máximo 400 MB desde una URL http o https, o de 100 MB como Data URI. El rigging admite modelos humanoides con textura.
El modelo puede tener como máximo 380,000 triángulos (un cuadrilátero cuenta como 2), y un modelo con más devuelve 400. Para mantenerte por debajo del límite, ejecuta primero la API de Remallado con un target_polycount de 300000 o menos, o 150000 o menos con topology: quad.
El rostro del personaje debe apuntar hacia el eje +Z, la dirección estándar hacia adelante de glTF. La estimación de la pose falla para un modelo que mira hacia otro eje.
Un archivo de más de 100 MB también debe cumplir estas reglas:
- Puede tener como máximo 10,000,000 de caras. Un archivo con más devuelve 400. Meshy cuenta las caras como triángulos, y una malla dibujada más de una vez cuenta una vez por copia.
- No debe usar compresión Draco.

Name
height_meters
Type
number
predeterminado 1.7
Description
La altura aproximada del personaje, en metros. Meshy la usa para escalar y aplicar el rigging al modelo con mayor precisión. Un valor negativo devuelve 400.
Name
texture_image_url
Type
string
⚠ obsoleto
Description
Omítelo cuando el modelo tenga sus propias texturas. Sin él, Meshy usa las texturas incrustadas en el archivo de model_url, o las texturas de la tarea de entrada. Si lo envías, esta imagen se convierte en la única textura del modelo con rig, y el modelo pierde sus mapas PBR.
La textura de color base con UV desenvuelto del modelo, como una URL pública o un Data URI. La imagen debe ser un archivo PNG de como máximo 20 MB. Otro formato de imagen devuelve 400.

Devuelve

El campo result de la respuesta contiene el ID de la nueva tarea de Rigging.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no se puede ejecutar. El mensaje de error indica qué problema encontró. Por ejemplo:
- Parámetro faltante: no se envió ni model_url ni input_task_id.
- Formato de modelo no válido: el archivo de model_url tiene una extensión no admitida. Solo se admite .glb.
- URL inaccesible: Meshy no puede descargar el archivo de model_url.
- Archivo de modelo demasiado grande: el archivo de model_url supera los 400 MB desde una URL http o https, o supera los 100 MB como Data URI.
- Demasiadas caras: el archivo de model_url supera los 100 MB y tiene más de 10,000,000 de caras. Reduce el número de caras y vuelve a enviar el archivo.
- Archivo de modelo ilegible: el archivo de model_url supera los 100 MB, y Meshy no puede leer su encabezado. Por ejemplo, es un GLB comprimido con Draco.
- Encabezado del modelo demasiado complejo: el archivo de model_url supera los 100 MB, y su encabezado tiene demasiadas mallas, nodos o registros para verificar. Reduce el número de objetos en el archivo y vuelve a enviarlo.
- Imagen demasiado grande: la imagen de texture_image_url supera los 20 MB.
- Formato de textura no válido: la imagen de texture_image_url no es un archivo PNG.
- Altura no válida: height_meters es negativo.
- Tarea de entrada no válida: input_task_id no hace referencia a una tarea válida de la API.
- Número de caras excedido: el modelo de entrada tiene más de 380,000 triángulos (un cuadrilátero cuenta como 2). Ejecuta la API de Remallado con un target_polycount de 300000 o menos, o 150000 o menos con topology: quad, antes de aplicar el rigging al modelo.
Corrige la solicitud y vuelve a enviarla. Consulta Errores.
Name
401 - Unauthorized
Description
Falta la clave de API o no es válida. Revisa el encabezado Authorization.
Name
402 - Payment Required
Description
Por ejemplo:
- Créditos insuficientes: la cuenta no tiene suficientes créditos para esta tarea, o la cuenta alcanzó un límite de créditos. Revisa tu saldo de créditos y vuelve a intentarlo.
- Plan gratuito: crear una tarea requiere un plan de pago. Mejora tu plan en la configuración de tu suscripción y vuelve a intentarlo.
Name
403 - Forbidden
Description
input_task_id es un modelo de bajo relieve, al que este endpoint no puede aplicar rigging. El mensaje es This model type does not support this operation. Envía un modelo diferente.
Name
422 - Unprocessable Entity
Description
Falló la estimación de la pose. Es posible que el modelo no sea un personaje humanoide válido. Envía un modelo de un personaje humanoide. Para model_url, verifica también que el personaje mire hacia el eje +Z.
Name
429 - Too Many Requests
Description
Superaste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.

GET/openapi/v1/rigging/:id

Obtener una tarea de Rigging

Devuelve una tarea de Rigging según su ID.

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
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

El objeto de tarea de Rigging.

DELETE/openapi/v1/rigging/:id

Eliminar una tarea de Rigging

Elimina permanentemente una tarea de Rigging, incluidos sus modelos y datos. No puedes deshacer una eliminación.

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

Parámetros de ruta

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

Estado de la tarea

Eliminar una tarea PENDING reembolsa los créditos que usó al crearla.

Una tarea IN_PROGRESS no se puede eliminar. La solicitud devuelve 409 Conflict, y la tarea sigue ejecutándose. Meshy no reembolsa una tarea que ya ha comenzado, por lo que eliminarla te costaría tanto los créditos como el resultado. Espera a que alcance el estado SUCCEEDED, FAILED o CANCELED, y luego elimínala.

Eliminar una tarea en un estado final (SUCCEEDED, FAILED o CANCELED) no reembolsa sus créditos.

Devuelve

200 OK cuando la tarea se elimina, o 409 Conflict cuando la tarea está IN_PROGRESS.

GET/openapi/v1/rigging

Listar tareas de Rigging

Devuelve una lista paginada de tus tareas de Rigging, de la más reciente a la más antigua. Para recorrer la lista, usa page_num y page_size.

Las tareas que creas con la API permanecen en la API y no aparecen en Mis Assets en la aplicación web. Para encontrar una tarea cuyo ID ya no tienes, usa este endpoint.

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

Transmite las actualizaciones de una tarea de Rigging como eventos enviados por el servidor (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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 event, with the same fields as the 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/.../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
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

Un flujo de objetos de tarea de Rigging como eventos enviados por el servidor.

Cada evento contiene el objeto de tarea completo, con la misma forma que devuelve el endpoint Get. Mientras la tarea esté en PENDING o IN_PROGRESS, sus campos de resultado aún no tienen valores.

El objeto de la tarea de rigging

Un objeto de tarea de rigging describe el rigging de un personaje. Contiene el estado, el progreso y los archivos de salida cuando la tarea tiene éxito.

Propiedades

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
}

Name
id
Type
string
Description
El ID de la tarea. Trátelo como una cadena opaca y no dependa de su formato.
Name
type
Type
string
Description
El tipo de tarea, siempre rig.
Name
status
Type
string
Description
El estado de la tarea, uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
progress
Type
integer
Description
Cuánto de la tarea se ha completado, como porcentaje. Es 0 hasta que la tarea comienza y 100 cuando tiene éxito.
Name
created_at
Type
timestamp
Description
Hora en que se creó la tarea, en milisegundos Unix.
Name
started_at
Type
timestamp
Description
Hora en que comenzó la tarea, en milisegundos Unix. Es 0 hasta que la tarea comienza.
Name
finished_at
Type
timestamp
Description
Hora en que finalizó la tarea, en milisegundos Unix. Es 0 hasta que la tarea finaliza.
Name
expires_at
Type
timestamp
Description
Hora en que expiran los archivos de resultado de la tarea, en milisegundos Unix. Después de este momento, Meshy puede eliminar los archivos.
Name
task_error
Type
object
Description
Los detalles del error cuando la tarea falla. Consulte Errores.
Name
consumed_credits
Type
integer
Description
El número de créditos que usó la tarea. Presente cuando el estado es PENDING, IN_PROGRESS o SUCCEEDED. Es 0 para una tarea FAILED, porque Meshy reembolsa los créditos cuando una tarea falla.
Name
result
Type
object
Description
Las URL de los archivos de salida. Hasta que la tarea tenga éxito, cada URL es una cadena vacía, y basic_animations es null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL de descarga del personaje rigged como archivo FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL de descarga del personaje rigged como archivo GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  URL de descarga de las animaciones de caminar y correr predeterminadas.
  Name
  walking_glb_url
  Type
  string
  Description
  La animación de caminar con piel, como archivo GLB.
  Name
  walking_fbx_url
  Type
  string
  Description
  La animación de caminar con piel, como archivo FBX.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  El esqueleto de la animación de caminar, como archivo GLB.
  Name
  running_glb_url
  Type
  string
  Description
  La animación de correr con piel, como archivo GLB.
  Name
  running_fbx_url
  Type
  string
  Description
  La animación de correr con piel, como archivo FBX.
  Name
  running_armature_glb_url
  Type
  string
  Description
  El esqueleto de la animación de correr, como archivo GLB.
Name
preceding_tasks
Type
integer
Description
El número de tareas por delante de esta en la cola. El valor solo es significativo mientras la tarea está PENDING.