API de Animação

Endpoints para descobrir animações disponíveis e aplicá-las a personagens com rig.

POST/openapi/v1/animations

Create an Animation Task

Este endpoint permite que você crie uma nova tarefa para aplicar uma animação a um personagem previamente rigado — uma ação predefinida da biblioteca de animações (action_id), várias ações predefinidas mescladas em um único arquivo (action_ids), ou um clipe de movimento gerado com a API Text to Motion (motion_task_id). Inclui opções de pós-processamento.

Parâmetros

Name
rig_task_id
Type
string
Obrigatório
Description
O id de uma tarefa de rigging concluída com sucesso (de POST /openapi/v1/rigging). O personagem dessa tarefa será animado.
Name
action_id
Type
integer
Description
O identificador da ação de animação predefinida a ser aplicada. Consulte a Referência da Biblioteca de animações para obter uma lista completa das animações disponíveis. Forneça exatamente um dos parâmetros action_id, action_ids ou motion_task_id.
Name
action_ids
Type
array of integers
Description
Várias ações de animação predefinidas a serem aplicadas de uma só vez, retornadas como um único arquivo contendo um clipe de animação por ação — útil para conduzir um personagem a partir de uma máquina de estados em um motor de jogo. Forneça de 1 a 10 valores de action_id da Referência da Biblioteca de animações; os ids devem ser únicos. Custa 3 créditos por ação. Forneça exatamente um dos parâmetros action_id, action_ids ou motion_task_id.
Passar um action_ids com um único elemento equivale a passar esse valor como action_id.
Name
motion_task_id
Type
string
Description
O id de uma tarefa de Text to Motion concluída com sucesso, a ser aplicada no lugar de uma ação predefinida. O clipe gerado é reajustado (retargeted) para o personagem rigado, e o clipe é capturado (snapshotted) no momento da criação, portanto essa tarefa não é afetada caso a tarefa de origem expire ou seja excluída posteriormente. Os assets da tarefa de origem são mantidos por 3 dias — aplique o clipe antes que ele expire. Requer um rig bípede. Forneça exatamente um dos parâmetros action_id, action_ids ou motion_task_id.
Name
post_process
Type
object
Description
Pós-processamento opcional para a saída da animação. Omita-o para receber os arquivos de animação padrão.

Aplica-se somente quando post_process is set

Name
operation_type
Type
string
Obrigatório
Description
O tipo de operação a ser realizada. Valores disponíveis: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
padrão 30
Description
A taxa de quadros de destino. Aplicável somente quando operation_type é change_fps. Valores permitidos: 24, 25, 30, 60.

Com action_ids, a tarefa retorna um único arquivo mesclado em vez de um arquivo por ação: animation_glb_url e animation_fbx_url apontam cada um para um único asset contendo todas as ações solicitadas como clipes separados.

Ordem dos clipes: a ordem do array action_ids, não a ordem numérica dos ids.
Nomes dos clipes: o nome da animação na biblioteca, correspondendo aos nomes que você obtém ao exportar todas as animações de um personagem como um único arquivo pelo aplicativo web da Meshy. Se dois ids solicitados resolverem para o mesmo nome de clipe, o posterior recebe um sufixo com seu action_id para manter os nomes únicos.
Pós-processamento: aplicado ao arquivo mesclado, não aos clipes individuais.

Com motion_task_id, o retargeting pode produzir uma animação apenas em GLB. Se você tiver solicitado post_process e nenhum FBX estiver disponível, a tarefa falha com um task_error e seus créditos são reembolsados automaticamente; sem post_process, a tarefa é bem-sucedida e animation_fbx_url fica vazio.

Retornos

A propriedade result da resposta contém o id da tarefa da animação recém-criada.

Modos de falha

Name
400 - Bad Request
Description
A requisição foi inaceitável. Causas comuns:
- Parâmetro ausente: rig_task_id está ausente, ou nenhum dos parâmetros action_id, action_ids e motion_task_id foi fornecido.
- Parâmetros conflitantes: mais de um dos parâmetros action_id, action_ids e motion_task_id foi fornecido — eles são mutuamente exclusivos.
- Tarefa de rig inválida: o rig_task_id é inválido ou se refere a uma tarefa falha/inexistente.
- ID de ação inválido: um action_id — ou um item de action_ids — não corresponde a uma animação válida.
- Excesso de ações: action_ids contém mais de 10 ids.
- Ações duplicadas: action_ids contém o mesmo id mais de uma vez.
- Tarefa de movimento não pronta: a tarefa referida por motion_task_id ainda não obteve SUCCEEDED.
- Rig não suportado: motion_task_id requer um rig bípede; rigs quadrúpedes são rejeitados.
Name
401 - Unauthorized
Description
A autenticação falhou. Verifique sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa.
Name
404 - Not Found
Description
A tarefa de rigging especificada por rig_task_id não foi encontrada, a tarefa de movimento especificada por motion_task_id não foi encontrada, ou o clipe de movimento expirou (os assets da tarefa de origem são mantidos por 3 dias).
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa.

Request

POST

/openapi/v1/animations

# Animate a rigged model with required params only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92
  }'

# Apply several preset actions and get one file with one clip per action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_ids": [10, 25, 92]
  }'

# Apply a generated Text to Motion clip instead of a preset action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
  }'

# With post-processing to change FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 24
    }
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

GET/openapi/v1/animations/:id

Recuperar uma Tarefa de Animação

Este endpoint permite recuperar uma tarefa de animação a partir de um id de tarefa válido. Consulte O Objeto de Tarefa de Animação para ver quais propriedades estão incluídas.

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de animação a ser recuperada.

Retornos

A resposta contém o objeto de Tarefa de Animação. Consulte a seção O Objeto de Tarefa de Animação para mais detalhes.

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/animations/:id

Excluir uma Tarefa de Animação

Este endpoint exclui permanentemente uma tarefa de animação, incluindo todos os modelos e dados associados. Esta ação é irreversível.

Parâmetros de Caminho

Name
id
Type
path
Description
O ID da tarefa de animação a ser excluída.

Status da Tarefa

Uma tarefa que ainda está PENDING é excluída e os créditos consumidos no momento da criação são reembolsados.

Uma tarefa que já está IN_PROGRESS não pode ser excluída: a requisição é rejeitada com 409 Conflict e a tarefa continua em execução. Créditos de uma tarefa que o worker já iniciou não são reembolsáveis, então excluí-la no meio da execução custaria tanto os créditos quanto o resultado. Aguarde até que ela atinja SUCCEEDED, FAILED ou CANCELED, e então exclua-a.

Uma tarefa em um estado terminal (SUCCEEDED, FAILED ou CANCELED) é excluída sem reembolso.

Retornos

Retorna 200 OK em caso de sucesso, ou 409 Conflict quando a tarefa está IN_PROGRESS.

Request

DELETE

/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/animations/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 is left 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."
}

GET/openapi/v1/animations

Listar Tarefas de Animação

Retorna uma lista paginada das tarefas de animação do solicitante, das mais recentes para as mais antigas. Paginação padrão via page_num e page_size.

Observe que as tarefas criadas por meio da API são gerenciadas por meio da API — elas não aparecem em Meus Assets no aplicativo web. Use este endpoint para encontrar uma tarefa cujo ID você não tem mais.

Request

GET

/openapi/v1/animations

curl "https://api.meshy.ai/openapi/v1/animations?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/animations/:id/stream

Transmitir uma Tarefa de Animação

Este endpoint transmite atualizações em tempo real para uma tarefa de Animação usando Server-Sent Events (SSE).

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de Animação a ser transmitida.

Retornos

Retorna um fluxo de The Animation Task Objects como Server-Sent Events.

Para tarefas PENDING ou IN_PROGRESS, o fluxo de resposta incluirá apenas os campos progress e status necessários.

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/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": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Animation Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

O Objeto Animation Task

O objeto Animation Task representa a unidade de trabalho para aplicar uma animação a um personagem com rig.

Propriedades

Name
id
Type
string
Description
Identificador único da tarefa.
Name
type
Type
string
Description
Tipo da tarefa de Animação. O valor é animate.
Name
status
Type
string
Description
Status da tarefa. Valores possíveis: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso da tarefa (0-100).
Name
created_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde epoch) de quando a tarefa foi criada.
Um carimbo de data/hora representa o número de milissegundos decorridos desde 1º de janeiro de 1970 UTC, seguindo o padrão RFC 3339. Por exemplo, sexta-feira, 1º de setembro de 2023, 12:00:00 GMT é representado como 1693569600000. Isso se aplica a todos os carimbos de data/hora na Meshy API.
Name
started_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde epoch) de quando a tarefa começou a ser processada. 0 se não foi iniciada.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde epoch) de quando a tarefa terminou. 0 se não foi finalizada.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde epoch) de quando os assets de resultado da tarefa expiram.
Name
task_error
Type
object
Description
Detalhes de erro para tarefas com falha. Consulte Erros para a referência completa do objeto task_error.
Name
consumed_credits
Type
integer
Description
O número de créditos consumidos por esta tarefa. Presente quando o status da tarefa é PENDING, IN_PROGRESS ou SUCCEEDED. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).
Name
result
Type
object
Description
Contém as URLs de animação de saída se a tarefa for SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL para download da animação no formato GLB. Para uma tarefa criada com action_ids, este único arquivo contém cada ação solicitada como um clipe separado.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL para download da animação no formato FBX. Para uma tarefa criada com action_ids, este único arquivo contém cada ação solicitada como um clipe separado.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL para download da animação processada no formato USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL para download da armature processada no formato FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL para download da animação com FPS alterado no formato FBX (por exemplo, se a operação change_fps foi usada).
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes na fila. Significativo apenas se o status for PENDING.

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

GET/openapi/v1/animations/library

List Animations

Retorna todas as animações da biblioteca, ordenadas por action_id. A resposta é uma lista completa, e não uma página, portanto uma única chamada é suficiente para preencher um seletor de ações. Os filtros restringem o resultado; omita todos para obter tudo.

Para navegar pelo mesmo catálogo visualmente, com uma prévia animada de cada ação, consulte a referência da Biblioteca de animações.

Este endpoint é gratuito — não consome créditos.

Parâmetros

Name
search
Type
string
Description
Correspondência de substring sem diferenciação entre maiúsculas e minúsculas em name ou key. A correspondência é literal, então % e _ são caracteres comuns, e não curingas.
Name
category
Type
string
Description
Correspondência exata em category.
Valores disponíveis:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Correspondência exata em sub_category. Aceito isoladamente — os nomes de sub-category não são únicos entre categorias (Transitioning aparece tanto em Fighting quanto em DailyActions), então, sem uma category, o filtro corresponde a essa sub-category onde quer que ela apareça.
Name
action_ids
Type
string
Description
Lista separada por vírgulas de valores de action_id a retornar, para resolver ids específicos em vez de navegar pelo catálogo. Aceita no máximo 200 ids. Ids que nenhuma animação possui simplesmente estão ausentes da resposta, então você também pode usar isso para verificar se ids que você armazenou ainda estão disponíveis.

Combinando filtros

Os filtros são aplicados em conjunto — cada um restringe ainda mais o resultado, de modo que uma animação só é retornada se satisfizer todos eles. Dentro de um único filtro, múltiplos valores correspondem a qualquer um deles: search corresponde a name ou key, e action_ids corresponde a qualquer id da lista.

Isso significa que uma combinação sem sobreposição retorna um array vazio em vez de um erro. A ação 92 é "Double Combo Attack", uma animação Fighting:

?action_ids=92&category=Fighting retorna a ação 92.
?action_ids=92&category=Dancing retorna [] — não é uma animação Dancing.
?action_ids=92&search=walk retorna [] — seu nome não corresponde a walk.

Para obter animações específicas independentemente de sua categoria, passe action_ids isoladamente.

Retornos

Retorna uma lista de Objetos de animação.

Todo action_id retornado aqui é aceito por Criar uma tarefa de animação acima, e todo id aceito por ela é retornado aqui. Animações desativadas estão ausentes de ambos. Se você armazenar a biblioteca em cache, atualize-a periodicamente para que um id desativado não permaneça no seu seletor.

Request

GET

/openapi/v1/animations/library

curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

O Objeto Animation

Name
action_id
Type
integer
Description
O valor a ser passado como action_id ao criar uma tarefa de animação. Único e estável, mas não contíguo — animações retiradas deixam lacunas na numeração, então nunca presuma que um intervalo de ids é válido.
Name
name
Type
string
Description
Rótulo legível para humanos, para exibição. Não é único: algumas animações compartilham um nome com uma variante diferente, então use action_id ou key como identidade.
Name
key
Type
string
Description
Slug único e estável para a animação. Use-o quando precisar de um identificador não numérico para indexar seu próprio armazenamento.
Name
category
Type
string
Description
Agrupamento de nível superior, ex: Fighting.
Name
sub_category
Type
string
Description
Agrupamento dentro da categoria, ex: AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL de um GIF animado que mostra uma prévia da ação, adequado para renderização direta em seu próprio seletor.

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}