API Animazione

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

POST/openapi/v1/animations

Create an Animation Task

Questo endpoint consente di creare un nuovo task per applicare un'animazione a un personaggio precedentemente sottoposto a rigging — sia un'azione preimpostata dalla libreria animazioni (action_id), sia una clip di movimento generata con la Text to Motion API (motion_task_id). Include opzioni di post-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 e motion_task_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 retargettizzata sul personaggio con rigging e la clip viene salvata come snapshot al momento della creazione, quindi questo task non è influenzato se il task sorgente scade o viene eliminato successivamente. 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 e motion_task_id.
Name
post_process
Type
object
Description
Post-elaborazione opzionale per l'output dell'animazione. Omettilo 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
Il frame rate di destinazione. Applicabile solo quando operation_type è change_fps. Valori consentiti: 24, 25, 30, 60.

Con motion_task_id, il retargeting potrebbe produrre un'animazione disponibile 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 di animazione appena creato.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non è stata accettata. Cause comuni:
- Parametro mancante: rig_task_id è mancante, oppure non è stato fornito né action_id né motion_task_id.
- Parametri in conflitto: sono stati forniti sia action_id che motion_task_id — sono reciprocamente esclusivi.
- Task di rigging non valido: rig_task_id non è valido o si riferisce a un task fallito/inesistente.
- ID azione non valido: action_id non corrisponde a un'animazione valida.
- 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; i rig quadrupedi vengono rifiutati.
Name
401 - Unauthorized
Description
Autenticazione fallita. 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 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 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 permanentemente 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.

Restituisce

Restituisce 200 OK in caso di successo.

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

// Returns 200 Ok on success.

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 con 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) di creazione del task.
Un timestamp rappresenta il numero di millisecondi trascorsi dal 1° gennaio 1970 UTC, secondo lo standard RFC 3339. Ad esempio, venerdì 1 settembre 2023 12:00:00 PM GMT è rappresentato come 1693569600000. Questo vale per tutti i timestamp in Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) di inizio elaborazione del task. 0 se non ancora avviato.
Name
finished_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) di fine del task. 0 se non ancora terminato.
Name
expires_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) di scadenza degli asset risultanti dal task.
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 di output se il task è SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL scaricabile per l'animazione in formato GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL scaricabile per l'animazione in formato FBX.
- 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
}