lowpoly verrà ritirato il 30 ott 2026. meshy-7 come modello di generazione 3D verrà ritirato il 31 dic 2026; come modello di texture resta disponibile. Cambia modello prima di queste date per evitare errori nelle richieste. Vedi tutte le deprecazioni
API Animazione
Applica animazioni a personaggi dotati di rig ed elenca le animazioni che puoi applicare.
Crea un task 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 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. Il task viene eseguito in background. Per la durata tipica di un task, vedi Tempi di elaborazione.
Request
POST
/openapi/v1/animations
# Animate a rigged model with required params onlycurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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 actioncurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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 actioncurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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 FPScurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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 del task di Rigging il cui personaggio deve essere animato, ottenuto da POST /openapi/v1/rigging. Il task 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 non invii action_ids o motion_task_id. L'ID dell'animazione preimpostata da applicare. Per l'elenco completo delle animazioni, vedi il riferimento Libreria animazioni oppure Elenca animazioni.
Il rig_type dell'animazione deve corrispondere al rig, altrimenti la richiesta restituisce 400. Qualsiasi animazione quadruped funziona su qualsiasi rig quadrupede, indipendentemente dall'animale indicato dalla sua category.
Name
action_ids
Type
array of integers
Obbligatorio
Description
Obbligatorio a meno che 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, vedi il riferimento Libreria animazioni.
Meshy restituisce un file con una clip di animazione per ogni azione, il che si adatta a una macchina a stati in un motore di gioco. Meshy addebita ogni azione presente nell'elenco. Vedi Prezzi.
Un elenco con un solo ID funziona allo stesso modo di inviare quell'ID come action_id.
Un'animazione il cui rig_type non corrisponde al rig restituisce 400.
Name
motion_task_id
Type
string
Obbligatorio
Description
Obbligatorio a meno che non invii action_id o action_ids. L'ID di un task Text to Motion la cui clip deve essere applicata al posto di un'azione preimpostata. Il task deve avere lo stato SUCCEEDED, e il rig deve essere bipede.
Meshy ritarget-izza la clip sul personaggio sottoposto a rigging. Copia la clip al momento della creazione di questo task, quindi questo task non viene influenzato se il task Text to Motion scade successivamente o lo elimini. Meshy conserva i file del task Text to Motion per 3 giorni, quindi applica la clip entro quel termine.
Nei file GLB e FBX, la clip è denominata retarget_clip.
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 retarget può produrre un'animazione solo in GLB. Se invii post_process e non è disponibile alcun file FBX, il task fallisce con un task_error, e Meshy rimborsa i tuoi crediti. Senza post_process, il task ha successo, 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 il frame rate in fps
fbx2usdz: converte l'animazione in USDZ
extract_armature: estrae l'armatura come file FBX
Name
fps
Type
integer
predefinito 30
Description
Il frame rate a cui passare, uno tra 24, 25, 30 o 60. Si applica solo quando operation_type è change_fps. Qualsiasi altro valore restituisce 400.
Con action_ids, il task restituisce un unico file unito anziché un file per ogni azione. animation_glb_url e animation_fbx_url puntano ciascuno a un unico file che contiene tutte le azioni richieste come clip separate. 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 ciascuna clip.
Valori restituiti
Il campo result della risposta contiene l'ID del nuovo task 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 di essi.
Task di rig non valido: rig_task_id non è un ID di task valido, non è un task di Rigging, oppure punta a un task che non ha avuto successo.
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.
Task di movimento non pronto: Il task 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.
Tipo di rig non corrispondente: Il rig_type di un'animazione non corrisponde al rig.
Correggi la richiesta, quindi inviala di nuovo. Vedi Errori.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
402 - Payment Required
Description
Ad esempio:
Crediti insufficienti: L'account non ha crediti sufficienti per questo task, oppure l'account ha raggiunto un limite di crediti. Controlla il tuo saldo crediti, quindi riprova.
Piano gratuito: La creazione di un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, quindi riprova.
Name
403 - Forbidden
Description
Il task 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 task o un file necessario alla richiesta. Si applica una delle seguenti situazioni:
Meshy non riesce a trovare il task rig_task_id tra i tuoi task. Controlla l'ID.
Meshy ha eliminato i file del task rig_task_id dopo la sua expires_at. Esegui di nuovo il rigging del personaggio.
Meshy non riesce a trovare il task motion_task_id. Controlla l'ID.
La clip di movimento è scaduta, perché Meshy conserva i file di un task Text to Motion per 3 giorni. Crea un altro task Text to Motion.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza. Attendi, quindi riprova. Vedi Limiti di frequenza.
// 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.
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.
// Error event exampleevent: errordata: {"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: messagedata: {"id": "018c425b-b2c6-727e-d333-3c1887i9h791","progress": 0,"status": "PENDING"}event: messagedata: {"id": "018c425b-b2c6-727e-d333-3c1887i9h791","progress": 50,"status": "IN_PROGRESS"}event: messagedata: { // 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": null,"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?..." }}
Ogni evento contiene l'oggetto task completo, con la stessa struttura restituita dall'endpoint Get. Mentre il task è in stato PENDING o IN_PROGRESS, i suoi campi di risultato non hanno ancora valori.
Un oggetto task Animazione descrive un'animazione applicata a un personaggio con rig. Contiene lo stato, il progress e i file dell'animazione quando il task ha successo.
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 è completato, in percentuale. È 0 finché il task non inizia e 100 quando ha successo.
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 fine del task, in millisecondi Unix. È 0 finché il task non termina.
Name
expires_at
Type
timestamp
Description
Ora di scadenza dei file di risultato del task, in millisecondi Unix.
Name
task_error
Type
object
Description
I dettagli dell'errore quando il task fallisce. È null a meno che lo stato non sia FAILED. Consulta Errori.
Name
consumed_credits
Type
integer
Description
Il numero di crediti usati 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 dell'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 al 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 davanti a questo nella coda. Il valore è significativo solo mentre il task è PENDING. Il campo viene omesso quando il valore è 0.
Restituisce ogni animazione della libreria, ordinata per action_id. La risposta è l'elenco completo, senza pagine, quindi una sola chiamata può popolare un selettore di azioni. I filtri restringono il risultato. Per ottenere ogni animazione, ometterli tutti.
Per sfogliare lo stesso elenco con un'anteprima animata di ciascuna azione, consulta il riferimento della Libreria animazioni.
Testo da cercare. Meshy restituisce le animazioni il cui name o key contiene questo testo, ignorando le maiuscole/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.
Le categorie delle animazioni biped:
WalkAndRun
BodyMovements
DailyActions
Fighting
Dancing
La categoria di un'animazione quadruped è un animale, ad esempio dog o horse.
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 compare sia in Fighting sia in DailyActions. Quindi senza category, il filtro corrisponde alla 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 a cui non corrisponde nessuna animazione. Quindi puoi anche usare 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 sovrapposizione restituisce un array vuoto, non un errore. L'azione 92 è "Double Combo Attack", un'animazione Fighting. Ad esempio:
Crea un'attività di Animazione accetta ogni action_id restituito da questo endpoint, e questo endpoint restituisce ogni ID che la creazione accetta. Nessuno dei due include animazioni ritirate. Se metti in cache la libreria, aggiornala di tanto in tanto, così un ID ritirato non resta nel tuo selettore.
Il valore da inviare come action_id quando crei un task di Animazione. È univoco e stabile, ma non contiguo. Le animazioni ritirate lasciano degli spazi vuoti nella numerazione, quindi non dare per scontato 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 per indicizzare il tuo archivio.
Name
category
Type
string
Description
Il gruppo di primo livello, ad esempio Fighting. Per un'animazione quadruped, è un animale, ad esempio dog o horse.
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 personalizzato.
Name
rig_type
Type
string
Description
Il tipo di rig su cui viene eseguita l'animazione, biped o quadruped. Corrisponde all'animation_type del task di Rigging. Un rig accetta solo animazioni del proprio tipo.