API Animazione

Endpoint per scoprire le Animazioni disponibili e applicarle a personaggi con rig.

POST/openapi/v1/animations

Crea un task di animazione

Questo endpoint consente di creare un nuovo task per applicare un'animazione a un personaggio precedentemente sottoposto a rigging — un'azione preimpostata dalla libreria animazioni (action_id), più azioni preimpostate unite in un unico file (action_ids), oppure una clip di movimento generata con la Text to Motion API (motion_task_id). Include opzioni di post-elaborazione.

Il task viene eseguito in background. Per informazioni sulla durata tipica, vedi Tempi di elaborazione.

Parametri

Name
rig_task_id
Type
string
Obbligatorio
Description
L'id di un task di rigging completato con successo (da POST /openapi/v1/rigging). Il personaggio di questo task verrà animato.
Name
action_id
Type
integer
Description
L'identificatore dell'azione di animazione preimpostata da applicare. Consulta il riferimento della Libreria animazioni per un elenco completo delle animazioni disponibili. Fornisci esattamente uno tra action_id, action_ids o motion_task_id.
Name
action_ids
Type
array of integers
Description
Diverse azioni di animazione preimpostate da applicare contemporaneamente, restituite come un unico file contenente una clip di animazione per ciascuna azione — utile per guidare un personaggio da una macchina a stati in un motore di gioco. Fornisci da 1 a 10 valori action_id dal riferimento della Libreria animazioni; gli id devono essere univoci. Costa 3 crediti per azione. Fornisci esattamente uno tra action_id, action_ids o motion_task_id.
Passare un action_ids con un singolo elemento equivale a passare quel valore come action_id.
Name
motion_task_id
Type
string
Description
L'id di un task Text to Motion completato con successo da applicare al posto di un'azione preimpostata. La clip generata viene adattata (retarget) al personaggio sottoposto a rigging e viene salvata come istantanea al momento della creazione, quindi questo task non viene influenzato se il task sorgente scade o viene eliminato in seguito. Gli asset del task sorgente vengono conservati per 3 giorni — applica la clip prima che scada. Richiede un rig bipede. Fornisci esattamente uno tra action_id, action_ids o motion_task_id.
Name
post_process
Type
object
Description
Post-elaborazione opzionale per l'output dell'animazione. Ometti questo parametro per ricevere i file di animazione standard.

Si applica solo quando post_process is set

Name
operation_type
Type
string
Obbligatorio
Description
Il tipo di operazione da eseguire. Valori disponibili: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
predefinito 30
Description
La frequenza fotogrammi target. Applicabile solo quando operation_type è change_fps. Valori consentiti: 24, 25, 30, 60.

Con action_ids, il task restituisce un unico file unito anziché un file per azione: animation_glb_url e animation_fbx_url puntano entrambi a un singolo asset contenente ogni azione richiesta come clip separata.

Ordine delle clip: l'ordine dell'array action_ids, non l'ordine numerico degli id.
Nomi delle clip: il nome dell'animazione nella libreria, corrispondente ai nomi che ottieni esportando tutte le animazioni di un personaggio come file unico dall'app web Meshy. Se due id richiesti corrispondono allo stesso nome di clip, il secondo viene suffissato con il proprio action_id per mantenere i nomi univoci.
Post-elaborazione: applicata al file unito, non alle singole clip.

Con motion_task_id, il retargeting potrebbe produrre un'animazione solo in GLB. Se hai richiesto post_process e non è disponibile alcun FBX, il task fallisce con un task_error e i tuoi crediti vengono rimborsati automaticamente; senza post_process il task ha esito positivo e animation_fbx_url risulta vuoto.

Valori restituiti

La proprietà result della risposta contiene l'id del task del nuovo task di animazione creato.

Modalità di fallimento

Name
400 - Bad Request
Description
La richiesta non è stata accettata. Cause comuni:
- Parametro mancante: rig_task_id è mancante, oppure non è stato fornito nessuno tra action_id, action_ids e motion_task_id.
- Parametri in conflitto: è stato fornito più di uno tra action_id, action_ids e motion_task_id — sono mutuamente esclusivi.
- Task di rigging non valido: Il rig_task_id non è valido o fa riferimento a un task non riuscito/inesistente.
- ID azione non valido: Un action_id — o una voce di action_ids — non corrisponde a un'animazione valida.
- Troppe azioni: action_ids contiene più di 10 id.
- Azioni duplicate: action_ids contiene lo stesso id più di una volta.
- Task di movimento non pronto: il task motion_task_id non è ancora SUCCEEDED.
- Rig non supportato: motion_task_id richiede un rig bipede; i rig quadrupedi vengono rifiutati.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. Controlla la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questo task.
Name
404 - Not Found
Description
Il task di rigging specificato da rig_task_id non è stato trovato, il task di movimento specificato da motion_task_id non è stato trovato, oppure la clip di movimento è scaduta (gli asset del task sorgente vengono conservati per 3 giorni).
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.

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

Recuperare un'attività di Animazione

Questo endpoint consente di recuperare un'attività di animazione dato un id di attività valido. Consulta L'oggetto Attività di Animazione per vedere quali proprietà sono incluse.

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività di animazione da recuperare.

Restituisce

La risposta contiene l'oggetto Attività di Animazione. Consulta la sezione L'oggetto Attività di Animazione per i dettagli.

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

Elimina un'attività di Animazione

Questo endpoint elimina definitivamente un'attività di animazione, inclusi tutti i modelli e i dati associati. Questa azione è irreversibile.

Parametri del percorso

Name
id
Type
path
Description
L'ID dell'attività di animazione da eliminare.

Stato dell'attività

Un'attività ancora in stato PENDING viene eliminata e i crediti consumati al momento della creazione vengono rimborsati.

Un'attività già in stato IN_PROGRESS non può essere eliminata: la richiesta viene rifiutata con 409 Conflict e l'attività continua a essere eseguita. I crediti per un'attività che il worker ha già iniziato a elaborare non sono rimborsabili, quindi eliminarla a metà esecuzione ti costerebbe sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

Un'attività in uno stato finale (SUCCEEDED, FAILED o CANCELED) viene eliminata senza rimborso.

Restituisce

Restituisce 200 OK in caso di successo, oppure 409 Conflict quando l'attività è in stato 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

Elenco delle attività di Animazione

Restituisce un elenco paginato delle attività di animazione del chiamante, dalla più recente alla meno recente. Paginazione standard tramite page_num e page_size.

Nota che le attività create tramite l'API sono gestite tramite l'API — non compaiono nella sezione My Assets dell'app web. Usa questo endpoint per trovare un'attività di cui non hai più l'ID.

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

Trasmetti in streaming un task di animazione

Questo endpoint trasmette in streaming aggiornamenti in tempo reale per un task di Animazione utilizzando Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore univoco del task di Animazione da trasmettere in streaming.

Restituisce

Restituisce uno stream di Oggetti Task di Animazione come Server-Sent Events.

Per i task PENDING o IN_PROGRESS, lo stream di risposta includerà solo i campi necessari progress e status.

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
}

L'oggetto Animation Task

L'oggetto Animation Task rappresenta l'unità di lavoro per applicare un'animazione a un personaggio dotato di rig.

Proprietà

Name
id
Type
string
Description
Identificatore univoco del task.
Name
type
Type
string
Description
Tipo del task di Animazione. Il valore è animate.
Name
status
Type
string
Description
Stato del task. Valori possibili: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress del task (0-100).
Name
created_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) in cui il task è stato creato.
Un timestamp rappresenta il numero di millisecondi trascorsi dal 1° gennaio 1970 UTC, seguendo lo standard RFC 3339. Ad esempio, venerdì 1 settembre 2023, ore 12:00:00 GMT è rappresentato come 1693569600000. Questo si applica a tutti i timestamp in Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) in cui il task ha iniziato l'elaborazione. 0 se non ancora avviato.
Name
finished_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) in cui il task è terminato. 0 se non ancora terminato.
Name
expires_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) in cui gli asset risultanti dal task scadono.
Name
task_error
Type
object
Description
Dettagli dell'errore per i task falliti. Consulta Errori per il riferimento completo dell'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questo task. Presente quando lo stato del task è PENDING, IN_PROGRESS, o SUCCEEDED. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di fallimento).
Name
result
Type
object
Description
Contiene gli URL dell'animazione risultante se il task è SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL scaricabile per l'animazione in formato GLB. Per un task creato con action_ids, questo singolo file contiene ogni azione richiesta come clip separata.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL scaricabile per l'animazione in formato FBX. Per un task creato con action_ids, questo singolo file contiene ogni azione richiesta come clip separata.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL scaricabile per l'animazione elaborata in formato USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL scaricabile per l'armatura elaborata in formato FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL scaricabile per l'animazione con FPS modificati in formato FBX (ad esempio, se è stata utilizzata l'operazione change_fps).
Name
preceding_tasks
Type
integer
Description
Il numero di task precedenti in coda. Significativo solo se lo stato è 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

Elenca animazioni

Restituisce ogni animazione nella libreria, ordinata per action_id. La risposta è un elenco completo anziché una pagina, quindi è sufficiente una sola chiamata per popolare un selettore di azioni. I filtri restringono il risultato; ometterli tutti significa recuperare tutto.

Per sfogliare lo stesso catalogo visivamente, con un'anteprima animata di ciascuna azione, consulta il riferimento della Libreria animazioni.

Questo endpoint è gratuito: non consuma crediti.

Parametri

Name
search
Type
string
Description
Corrispondenza di sottostringa senza distinzione tra maiuscole e minuscole su name o key. La corrispondenza è letterale, quindi % e _ sono caratteri ordinari e non caratteri jolly.
Name
category
Type
string
Description
Corrispondenza esatta su category.
Valori disponibili:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Corrispondenza esatta su sub_category. Accettato da solo — i nomi delle sotto-categorie non sono univoci tra le categorie (Transitioning compare sia in Fighting che in DailyActions), quindi senza category il filtro corrisponde a quella sotto-categoria ovunque compaia.
Name
action_ids
Type
string
Description
Elenco separato da virgole di valori action_id da restituire, per risolvere id specifici anziché sfogliare l'elenco. Accetta al massimo 200 id. Gli id non associati a nessuna animazione sono semplicemente assenti dalla risposta, quindi puoi usare questo anche per verificare se gli id che hai memorizzato sono ancora disponibili.

Combinare i filtri

I filtri vengono applicati insieme — ciascuno restringe ulteriormente il risultato, quindi un'animazione viene restituita solo se soddisfa tutti i filtri. All'interno di un singolo filtro, più valori corrispondono a uno qualsiasi di essi: search corrisponde a name o key, e action_ids corrisponde a qualsiasi id nell'elenco.

Questo significa che una combinazione senza sovrapposizione restituisce un array vuoto anziché un errore. L'azione 92 è "Double Combo Attack", un'animazione Fighting:

?action_ids=92&category=Fighting restituisce l'azione 92.
?action_ids=92&category=Dancing restituisce [] — non è un'animazione Dancing.
?action_ids=92&search=walk restituisce [] — il suo nome non corrisponde a walk.

Per recuperare animazioni specifiche indipendentemente dalla loro categoria, passa action_ids da solo.

Restituisce

Restituisce un elenco di Oggetti Animazione.

Ogni action_id restituito qui è accettato da Crea un'attività di animazione sopra, e ogni id che essa accetta viene restituito qui. Le animazioni ritirate sono assenti da entrambi. Se metti in cache la libreria, aggiornala periodicamente in modo che un id ritirato non rimanga nel tuo selettore.

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

L'oggetto Animazione

Name
action_id
Type
integer
Description
Il valore da passare come action_id quando si crea un'attività di animazione. Univoco e stabile, ma non contiguo — le animazioni ritirate lasciano dei vuoti nella numerazione, quindi non dare mai per scontato che un intervallo di id sia valido.
Name
name
Type
string
Description
Etichetta leggibile per l'uomo, ai fini della visualizzazione. Non univoca: alcune animazioni condividono un nome con una variante diversa, quindi usa action_id o key come identità.
Name
key
Type
string
Description
Slug univoco e stabile per l'animazione. Usalo quando hai bisogno di un identificatore non numerico su cui basare la tua chiave di archiviazione.
Name
category
Type
string
Description
Raggruppamento di primo livello, ad es. Fighting.
Name
sub_category
Type
string
Description
Raggruppamento all'interno della categoria, ad es. AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL di una GIF animata che mostra un'anteprima dell'azione, adatta per essere visualizzata direttamente nel tuo selettore.

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