API Animazione

Applica animazioni a personaggi dotati di rig ed elenca le animazioni che puoi applicare.

POST/openapi/v1/animations

Crea un'attività di Animazione

Crea un'attività di Animazione, che applica un'animazione a un personaggio che hai già sottoposto a rigging. L'animazione può essere una delle seguenti:

Un'azione preimpostata dalla libreria delle animazioni (action_id)
Diverse azioni preimpostate unite in un unico file (action_ids)
Una clip di movimento generata con la Text to Motion API (motion_task_id)

Puoi anche post-elaborare l'output. L'attività viene eseguita in background. Per sapere quanto tempo richiede di solito un'attività, consulta Tempi di elaborazione.

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

Parametri

Name
rig_task_id
Type
string
Obbligatorio
Description
L'ID dell'attività di Rigging il cui personaggio deve essere animato, ottenuto da POST /openapi/v1/rigging. L'attività deve avere lo stato SUCCEEDED.

Invia esattamente uno tra action_id, action_ids e motion_task_id.

Name
action_id
Type
integer
Obbligatorio
Description
Obbligatorio a meno che tu non invii action_ids o motion_task_id. L'ID dell'animazione preimpostata da applicare. Per l'elenco completo delle animazioni, consulta il riferimento della Libreria animazioni oppure Elenca animazioni.

Name
action_ids
Type
array of integers
Obbligatorio
Description
Obbligatorio a meno che tu non invii action_id o motion_task_id. Gli ID di 1-10 animazioni preimpostate da applicare contemporaneamente, senza ripetizioni. Più di 10 ID, o un ID ripetuto, restituisce 400. Per gli ID, consulta il riferimento della Libreria animazioni.
Meshy restituisce un file con una clip di animazione per ogni azione, il che è adatto a una macchina a stati in un motore di gioco. Meshy addebita ogni azione presente nell'elenco. Consulta Prezzi.
Un elenco con un solo ID funziona come se si inviasse quell'ID come action_id.

Name
motion_task_id
Type
string
Obbligatorio
Description
Obbligatorio a meno che tu non invii action_id o action_ids. L'ID di un'attività Text to Motion la cui clip deve essere applicata al posto di un'azione preimpostata. L'attività deve avere lo stato SUCCEEDED, e il rig deve essere bipede.
Meshy ritarga la clip sul personaggio dotato di rig. Copia la clip quando crei questa attività, quindi questa attività non è influenzata se l'attività Text to Motion scade successivamente o se la elimini. Meshy conserva i file dell'attività Text to Motion per 3 giorni, quindi applica la clip prima di quel termine.

Name
post_process
Type
object
Description
Post-elaborazione per l'output dell'animazione. Omettilo per ottenere i file di animazione standard.
Con motion_task_id, il retargeting può produrre un'animazione solo in GLB. Se invii post_process e non è disponibile alcun file FBX, l'attività fallisce con un task_error, e Meshy rimborsa i tuoi crediti. Senza post_process, l'attività ha esito positivo, e animation_fbx_url è vuoto.

Si applica solo quando post_process is set

Name
operation_type
Type
string
Description
L'operazione da eseguire. Senza di essa, Meshy non crea alcun file aggiuntivo. Un valore non presente nell'elenco seguente restituisce 400.
Valori disponibili:
- change_fps: cambia la frequenza fotogrammi in fps
- fbx2usdz: converte l'animazione in USDZ
- extract_armature: estrae l'armatura come file FBX
Name
fps
Type
integer
predefinito 30
Description
La frequenza fotogrammi a cui cambiare, una tra 24, 25, 30 o 60. Si applica solo quando operation_type è change_fps. Qualsiasi altro valore restituisce 400.

Con action_ids, l'attività restituisce un unico file unito invece di un file per ogni azione. animation_glb_url e animation_fbx_url puntano ciascuno a un unico file che contiene ogni azione richiesta come clip separata. In quel file:

Ordine delle clip: l'ordine dell'array action_ids, non l'ordine numerico degli ID.
Nomi delle clip: il nome dell'animazione nella libreria. Questi corrispondono ai nomi che ottieni quando esporti tutte le animazioni di un personaggio come un unico file dall'app web di Meshy. Se due ID richiesti hanno lo stesso nome di clip, Meshy aggiunge l'action_id a quello successivo per mantenere i nomi univoci.
Post-elaborazione: Meshy la applica al file unito, non a ogni singola clip.

Valori restituiti

Il campo result della risposta contiene l'ID della nuova attività di Animazione.

Modalità di fallimento

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Il messaggio di errore indica quale problema è stato rilevato. Ad esempio:
- Parametro mancante: rig_task_id manca, oppure non è stato inviato nessuno tra action_id, action_ids e motion_task_id.
- Parametri in conflitto: La richiesta contiene più di uno tra action_id, action_ids e motion_task_id. Invia solo uno.
- Attività di rig non valida: rig_task_id non è un ID attività valido, non è un'attività di Rigging, o punta a un'attività che non è andata a buon fine.
- ID azione non valido: Un action_id, o una voce in action_ids, non è un'animazione valida.
- Troppe azioni: action_ids contiene più di 10 ID.
- Azioni duplicate: action_ids contiene lo stesso ID più di una volta.
- Attività di movimento non pronta: L'attività motion_task_id non ha ancora raggiunto lo stato SUCCEEDED.
- Rig non supportato: motion_task_id richiede un rig bipede, e Meshy rifiuta un rig quadrupede.
Correggi la richiesta, quindi inviala di nuovo. Consulta Errori.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'intestazione Authorization.
Name
402 - Payment Required
Description
Ad esempio:
- Crediti insufficienti: L'account non ha crediti sufficienti per questa attività, oppure ha raggiunto un limite di credito. Controlla il tuo saldo crediti, quindi riprova.
- Piano gratuito: La creazione di un'attività richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni di abbonamento, quindi riprova.
Name
403 - Forbidden
Description
L'attività rig_task_id è un modello a bassorilievo, che questo endpoint non può animare. Il messaggio è This model type does not support this operation. Esegui il rigging di un modello diverso.
Name
404 - Not Found
Description
Meshy non riesce a trovare un'attività o un file richiesto dalla richiesta. Si applica uno dei seguenti casi:
- Meshy non riesce a trovare l'attività rig_task_id tra le tue attività. Controlla l'ID.
- Meshy ha eliminato i file dell'attività rig_task_id dopo il suo expires_at. Esegui di nuovo il rigging del personaggio.
- Meshy non riesce a trovare l'attività motion_task_id. Controlla l'ID.
- La clip di movimento è scaduta, perché Meshy conserva i file di un'attività Text to Motion per 3 giorni. Crea un'altra attività Text to Motion.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza. Attendi, quindi riprova. Consulta Limiti di frequenza.

GET/openapi/v1/animations/:id

Recupera un'attività di Animazione

Restituisce un'attività di Animazione in base al suo ID.

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
}

Parametri

Name
id
Type
path
Description
L'ID dell'attività dalla risposta di creazione.

Restituisce

L'oggetto attività di Animazione.

DELETE/openapi/v1/animations/:id

Elimina un'attività di Animazione

Elimina definitivamente un'attività di Animazione, inclusi i suoi modelli e i suoi dati. Non è possibile annullare un'eliminazione.

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

Parametri del percorso

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

Stato dell'attività

Eliminare un'attività PENDING rimborsa i crediti utilizzati al momento della sua creazione.

Un'attività IN_PROGRESS non può essere eliminata. La richiesta restituisce 409 Conflict, e l'attività continua a essere eseguita. Meshy non rimborsa un'attività che è già stata avviata, quindi eliminarla ti farebbe perdere sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

Eliminare un'attività in uno stato finale (SUCCEEDED, FAILED o CANCELED) non rimborsa i suoi crediti.

Restituisce

200 OK quando l'attività viene eliminata, oppure 409 Conflict quando l'attività è IN_PROGRESS.

GET/openapi/v1/animations

Elenco dei task di Animazione

Restituisce un elenco paginato dei tuoi task di Animazione, dal più recente al meno recente. Per scorrere l'elenco, usa page_num e page_size.

I task creati tramite l'API non compaiono in My Assets nell'app web, quindi li gestisci tramite l'API. Per trovare un task di cui non hai più l'ID, usa questo endpoint.

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

Esegui lo streaming di un task di Animazione

Esegue lo streaming degli aggiornamenti di un task di Animazione come Server-Sent Events (SSE).

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

Parametri

Name
id
Type
path
Description
L'ID del task dalla risposta di creazione.

Valori restituiti

Uno stream di oggetti task di Animazione come Server-Sent Events.

Ogni evento contiene l'oggetto task completo, nello stesso formato restituito dall'endpoint Get. Mentre il task è PENDING o IN_PROGRESS, i suoi campi dei risultati non hanno ancora valori.

L'oggetto task Animazione

Un oggetto task Animazione descrive un'animazione applicata a un personaggio con rig. Contiene lo stato, il progress e i file di animazione quando il task riesce.

Proprietà

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
}

Name
id
Type
string
Description
L'ID del task. Trattalo come una stringa opaca e non fare affidamento sul suo formato.
Name
type
Type
string
Description
Il tipo di task, sempre animate.
Name
status
Type
string
Description
Lo stato del task, uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
progress
Type
integer
Description
Quanto del task è stato completato, in percentuale. È 0 finché il task non inizia e 100 quando riesce.
Name
created_at
Type
timestamp
Description
Ora di creazione del task, in millisecondi Unix.
Name
started_at
Type
timestamp
Description
Ora di avvio del task, in millisecondi Unix. È 0 finché il task non inizia.
Name
finished_at
Type
timestamp
Description
Ora di completamento del task, in millisecondi Unix. È 0 finché il task non finisce.
Name
expires_at
Type
timestamp
Description
Ora di scadenza dei file risultato del task, in millisecondi Unix.
Name
task_error
Type
object
Description
I dettagli dell'errore quando il task fallisce. Vedi Errori.
Name
consumed_credits
Type
integer
Description
Il numero di crediti utilizzati dal task. Presente quando lo stato è PENDING, IN_PROGRESS o SUCCEEDED. È 0 per un task FAILED, perché Meshy rimborsa i crediti quando un task fallisce.
Name
result
Type
object
Description
URL di download per i file di animazione, quando il task ha lo stato SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  L'animazione come file 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
  L'animazione come file 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
  L'animazione elaborata come file USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  L'armatura elaborata come file FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  L'animazione con il frame rate modificato, come file FBX, ad esempio quando hai usato l'operazione change_fps.
Name
preceding_tasks
Type
integer
Description
Il numero di task che precedono questo nella coda. Il valore è significativo solo mentre il task è PENDING.

GET/openapi/v1/animations/library

Elenca animazioni

Restituisce ogni animazione presente nella libreria, ordinata per action_id. La risposta è l'elenco completo, senza paginazione, quindi una sola chiamata può popolare un selettore di azioni. I filtri restringono il risultato. Per ottenere tutte le animazioni, omettili tutti.

Per sfogliare lo stesso elenco con un'anteprima animata di ogni azione, consulta il riferimento della Libreria animazioni.

Questa richiesta non costa crediti.

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

Parametri

Name
search
Type
string
Description
Testo da cercare. Meshy restituisce le animazioni il cui name o key contiene questo testo, senza distinzione tra maiuscole e minuscole. Meshy confronta il testo letteralmente, quindi % e _ non sono caratteri jolly.
Name
category
Type
string
Description
La categoria da elencare, come corrispondenza esatta. Una categoria sconosciuta restituisce un elenco vuoto.
Valori disponibili:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
La sottocategoria da elencare, come corrispondenza esatta. Puoi inviarla senza category. I nomi delle sottocategorie non sono univoci tra le categorie. Ad esempio, Transitioning è presente sia in Fighting che in DailyActions. Quindi, senza category, il filtro trova corrispondenze con la sottocategoria in ogni categoria.
Name
action_ids
Type
string
Description
Le animazioni da restituire, fino a 200 valori action_id separati da virgola. Usalo per cercare ID specifici invece di sfogliare l'elenco. Più di 200 ID restituisce 400.
La risposta omette un ID che non corrisponde a nessuna animazione. Quindi puoi usare anche questo filtro per verificare se gli ID che hai memorizzato sono ancora disponibili.

Combinare i filtri

Meshy applica i filtri insieme. Ciascuno restringe il risultato, quindi Meshy restituisce un'animazione solo se corrisponde a tutti. All'interno di un singolo filtro, può corrispondere uno qualsiasi dei suoi valori. Ad esempio, search corrisponde a name o key, e action_ids corrisponde a qualsiasi ID nell'elenco.

Quindi una combinazione senza sovrapposizioni restituisce un array vuoto, non un errore. L'azione 92 è "Double Combo Attack", un'animazione Fighting. Ad esempio:

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

Per ottenere animazioni specifiche in qualsiasi categoria, invia action_ids da solo.

Restituisce

Un elenco di oggetti animazione.

Crea un'attività di Animazione accetta ogni action_id restituito da questo endpoint, e questo endpoint restituisce ogni ID accettato dalla creazione. Nessuno dei due include le animazioni ritirate. Se metti in cache la libreria, aggiornala di tanto in tanto, così un ID ritirato non resta nel tuo selettore.

L'oggetto animazione

Un oggetto animazione descrive un'Animazione nella libreria.

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

Name
action_id
Type
integer
Description
Il valore da inviare come action_id quando si crea un task di Animazione. È univoco e stabile, ma non contiguo. Le animazioni ritirate lasciano degli spazi vuoti nella numerazione, quindi non bisogna presumere che ogni ID in un intervallo sia valido.
Name
name
Type
string
Description
Il nome visualizzato dell'animazione. Non è univoco, perché alcune animazioni condividono il nome con un'altra variante. Per identificare un'animazione, usa action_id o key.
Name
key
Type
string
Description
Uno slug univoco e stabile per l'animazione. Usalo quando hai bisogno di un ID non numerico su cui basare il tuo storage.
Name
category
Type
string
Description
Il gruppo di livello superiore, ad esempio Fighting.
Name
sub_category
Type
string
Description
Il gruppo all'interno della categoria, ad esempio AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL di un'anteprima GIF animata dell'azione. Puoi mostrarla direttamente nel tuo selettore.