API de Rigging

Adicione um esqueleto (armature) a um modelo 3D humanoide e vincule a malha a ele, para que o personagem esteja pronto para ser animado. Para aplicar animações a um personagem com rig, consulte a API de Animação.

O rigging funciona bem apenas com personagens humanoides (bípedes) padrão que tenham uma estrutura de membros e corpo claramente definida.

POST/openapi/v1/rigging

Criar uma tarefa de Rigging

Cria uma tarefa de Rigging para um modelo 3D. Quando a tarefa for concluída com sucesso, ela retorna um personagem com rig em formatos padrão e, opcionalmente, animações básicas de caminhada e corrida.

A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, consulte Tempos de processamento.

O Rigging não é adequado para estes modelos:

Malhas sem textura
Assets não humanoides
Assets humanoides com estrutura de membros e corpo pouco definida

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
Obrigatório
Description
Obrigatório, a menos que você envie model_url. O ID da tarefa cujo modelo você deseja riggar. O Meshy oferece suporte a modelos humanoides com textura.
O modelo pode ter no máximo 380.000 triângulos (um quad conta como 2), e um modelo com mais retorna 400. Para ficar dentro do limite, execute a API de Remesh nele primeiro com um target_polycount de 300000 ou menos, ou 150000 ou menos com topology: quad.

Name
model_url
Type
string
Obrigatório
Description
Obrigatório, a menos que você envie input_task_id. O modelo a ser riggado, como uma URL pública ou um data URI. Se você enviar ambos, o Meshy usa input_task_id.
O modelo deve ser um arquivo GLB (.glb) de no máximo 400 MB a partir de uma URL http ou https, ou 100 MB como data URI. O Rigging oferece suporte a modelos humanoides com textura.
O modelo pode ter no máximo 380.000 triângulos (um quad conta como 2), e um modelo com mais retorna 400. Para ficar dentro do limite, execute a API de Remesh nele primeiro com um target_polycount de 300000 ou menos, ou 150000 ou menos com topology: quad.
O rosto do personagem deve apontar para o eixo +Z, a direção padrão de "para frente" do glTF. A estimativa de pose falha para um modelo voltado para outro eixo.
Um arquivo acima de 100 MB também deve seguir estas regras:
- Pode ter no máximo 10.000.000 de faces. Um arquivo com mais retorna 400. O Meshy conta faces como triângulos, e uma malha desenhada mais de uma vez conta uma vez por cópia.
- Não deve usar compressão Draco.

Name
height_meters
Type
number
padrão 1.7
Description
A altura aproximada do personagem, em metros. O Meshy a usa para escalar e riggar o modelo com mais precisão. Um valor negativo retorna 400.
Name
texture_image_url
Type
string
⚠ obsoleto
Description
Deixe de fora quando o modelo tiver suas próprias texturas. Sem ele, o Meshy usa as texturas incorporadas no arquivo model_url, ou as texturas da tarefa de entrada. Se você o enviar, essa imagem se torna a única textura do modelo riggado, e o modelo perde seus mapas PBR.
A textura de cor base com UV desdobrado do modelo, como uma URL pública ou um data URI. A imagem deve ser um arquivo PNG de no máximo 20 MB. Outro formato de imagem retorna 400.

Retornos

O campo result da resposta contém o ID da nova tarefa de Rigging.

Modos de falha

Name
400 - Bad Request
Description
A requisição não pode ser executada. A mensagem de erro indica qual problema foi encontrado. Por exemplo:
- Parâmetro ausente: Nem model_url nem input_task_id foram enviados.
- Formato de modelo inválido: O arquivo model_url tem uma extensão não suportada. Apenas .glb é suportado.
- URL inacessível: O Meshy não consegue baixar o arquivo model_url.
- Arquivo de modelo muito grande: O arquivo model_url está acima de 400 MB a partir de uma URL http ou https, ou acima de 100 MB como data URI.
- Muitas faces: O arquivo model_url está acima de 100 MB e tem mais de 10.000.000 de faces. Reduza a contagem de faces e envie o arquivo novamente.
- Arquivo de modelo ilegível: O arquivo model_url está acima de 100 MB, e o Meshy não consegue ler seu cabeçalho. Por exemplo, é um GLB comprimido com Draco.
- Cabeçalho do modelo muito complexo: O arquivo model_url está acima de 100 MB, e seu cabeçalho tem malhas, nós ou registros demais para verificar. Reduza o número de objetos no arquivo e envie-o novamente.
- Imagem muito grande: A imagem texture_image_url está acima de 20 MB.
- Formato de textura inválido: A imagem texture_image_url não é um arquivo PNG.
- Altura inválida: height_meters é negativo.
- Tarefa de entrada inválida: input_task_id não se refere a uma tarefa de API válida.
- Contagem de faces excedida: O modelo de entrada tem mais de 380.000 triângulos (um quad conta como 2). Execute a API de Remesh nele com um target_polycount de 300000 ou menos, ou 150000 ou menos com topology: quad, antes de riggar o modelo.
Corrija a requisição e envie-a novamente. Consulte Erros.
Name
401 - Unauthorized
Description
A chave de API está ausente ou inválida. Verifique o cabeçalho Authorization.
Name
402 - Payment Required
Description
Por exemplo:
- Créditos insuficientes: A conta não tem créditos suficientes para esta tarefa, ou a conta atingiu um limite de créditos. Verifique seu saldo de créditos e tente novamente.
- Plano gratuito: Criar uma tarefa requer um plano pago. Faça upgrade do seu plano nas configurações de assinatura e tente novamente.
Name
403 - Forbidden
Description
input_task_id é um modelo de baixo-relevo, que este endpoint não consegue riggar. A mensagem é This model type does not support this operation. Envie um modelo diferente.
Name
422 - Unprocessable Entity
Description
A estimativa de pose falhou. O modelo pode não ser um personagem humanoide válido. Envie um modelo de um personagem humanoide. Para model_url, verifique também se o personagem está voltado para o eixo +Z.
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.

GET/openapi/v1/rigging/:id

Obter uma tarefa de Rigging

Retorna uma tarefa de Rigging pelo seu 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
O ID da tarefa retornado na resposta de criação.

Retornos

O objeto de tarefa de Rigging.

DELETE/openapi/v1/rigging/:id

Excluir uma tarefa de Rigging

Exclui permanentemente uma tarefa de Rigging, incluindo seus modelos e dados. Você não pode desfazer uma exclusão.

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 caminho

Name
id
Type
path
Description
O ID da tarefa a ser excluída.

Status da tarefa

Excluir uma tarefa PENDING reembolsa os créditos usados quando você a criou.

Uma tarefa IN_PROGRESS não pode ser excluída. A solicitação retorna 409 Conflict, e a tarefa continua em execução. Meshy não reembolsa uma tarefa que já foi iniciada, então excluí-la custaria tanto os créditos quanto o resultado. Aguarde até que ela atinja o status SUCCEEDED, FAILED ou CANCELED, e então exclua-a.

Excluir uma tarefa em um status final (SUCCEEDED, FAILED ou CANCELED) não reembolsa seus créditos.

Retornos

200 OK quando a tarefa é excluída, ou 409 Conflict quando a tarefa está IN_PROGRESS.

GET/openapi/v1/rigging

List Rigging tasks

Retorna uma lista paginada das suas tarefas de Rigging, da mais recente para a mais antiga. Para navegar pela lista, use page_num e page_size.

As tarefas que você cria com a API permanecem na API e não aparecem em My Assets no aplicativo web. Para encontrar uma tarefa cujo ID você não tem mais, use 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 uma tarefa de Rigging em stream

Transmite as atualizações de uma tarefa de Rigging como Server-Sent Events (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
O ID da tarefa retornado na resposta de criação.

Retornos

Um stream de objetos de tarefa de Rigging como Server-Sent Events.

Cada evento contém o objeto de tarefa completo, no mesmo formato retornado pelo endpoint Get. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, seus campos de resultado ainda não têm valores.

O objeto de tarefa de Rigging

Um objeto de tarefa de Rigging descreve o rigging de um personagem. Ele contém o status, o progress e os arquivos de saída quando a tarefa é concluída com sucesso.

Propriedades

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
O ID da tarefa. Trate-o como uma string opaca e não dependa do seu formato.
Name
type
Type
string
Description
O tipo da tarefa, sempre rig.
Name
status
Type
string
Description
O status da tarefa, um dos seguintes: PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.
Name
progress
Type
integer
Description
O quanto da tarefa já foi concluído, em porcentagem. É 0 até a tarefa começar e 100 quando ela é concluída com sucesso.
Name
created_at
Type
timestamp
Description
Horário em que a tarefa foi criada, em milissegundos Unix.
Name
started_at
Type
timestamp
Description
Horário em que a tarefa começou, em milissegundos Unix. É 0 até a tarefa começar.
Name
finished_at
Type
timestamp
Description
Horário em que a tarefa terminou, em milissegundos Unix. É 0 até a tarefa terminar.
Name
expires_at
Type
timestamp
Description
Horário em que os arquivos de resultado da tarefa expiram, em milissegundos Unix. Após esse horário, a Meshy pode excluir os arquivos.
Name
task_error
Type
object
Description
Os detalhes do erro quando a tarefa falha. Veja Erros.
Name
consumed_credits
Type
integer
Description
O número de créditos que a tarefa usou. Presente quando o status é PENDING, IN_PROGRESS ou SUCCEEDED. É 0 para uma tarefa FAILED, pois a Meshy reembolsa os créditos quando uma tarefa falha.
Name
result
Type
object
Description
As URLs dos arquivos de saída. Até a tarefa ser concluída com sucesso, cada URL é uma string vazia, e basic_animations é null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL de download do personagem com rigging como um arquivo FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL de download do personagem com rigging como um arquivo GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  URLs de download para as animações padrão de caminhada e corrida.
  Name
  walking_glb_url
  Type
  string
  Description
  A animação de caminhada com skin, como um arquivo GLB.
  Name
  walking_fbx_url
  Type
  string
  Description
  A animação de caminhada com skin, como um arquivo FBX.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  A armature da animação de caminhada, como um arquivo GLB.
  Name
  running_glb_url
  Type
  string
  Description
  A animação de corrida com skin, como um arquivo GLB.
  Name
  running_fbx_url
  Type
  string
  Description
  A animação de corrida com skin, como um arquivo FBX.
  Name
  running_armature_glb_url
  Type
  string
  Description
  A armature da animação de corrida, como um arquivo GLB.
Name
preceding_tasks
Type
integer
Description
O número de tarefas à frente desta na fila. O valor só é relevante enquanto a tarefa está PENDING.