API di Animazione

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

POST/openapi/v1/animations

Crea un'attività di Animazione

Questo endpoint consente di creare una nuova attività per applicare una specifica azione di animazione a un personaggio precedentemente sottoposto a rigging. Include opzioni di post-elaborazione.

Parametri

Name
rig_task_id
Type
string
Obbligatorio
Description
L'id di un'attività di rigging completata correttamente (da POST /openapi/v1/rigging). Il personaggio di questa attività verrà animato.
Name
action_id
Type
integer
Obbligatorio
Description
L'identificatore dell'azione di animazione da applicare. Consulta il Riferimento della Libreria animazioni per un elenco completo delle animazioni disponibili.
Name
post_process
Type
object
Description
Post-elaborazione opzionale per l'output dell'animazione. Omettila 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.

Restituisce

La proprietà result della risposta contiene l'id dell'attività di animazione appena creata.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante: manca rig_task_id o action_id.
- Attività di rig non valida: rig_task_id non è valido o fa riferimento a un'attività non riuscita/inesistente.
- ID azione non valido: action_id non corrisponde a un'animazione valida.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. Controlla la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questa attività.
Name
404 - Not Found
Description
L'attività di rigging specificata da rig_task_id non è stata trovata.
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
  }'

# 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

Recupera un'attività di Animazione

Questo endpoint ti consente di recuperare un'attività di animazione dato un id 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.

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/:id/stream

Esegui lo streaming di un'attività di Animazione

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

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività di Animazione di cui eseguire lo streaming.

Restituisce

Restituisce uno stream degli oggetti attività di Animazione come Server-Sent Events.

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

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 Attività di Animazione

L'oggetto Attività di Animazione rappresenta l'unità di lavoro per applicare un'animazione a un personaggio con rig.

Proprietà

Name
id
Type
string
Description
Identificatore univoco dell'attività.
Name
type
Type
string
Description
Tipo dell'attività di Animazione. Il valore è animate.
Name
status
Type
string
Description
Stato dell'attività. Valori possibili: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress dell'attività (0-100).
Name
created_at
Type
timestamp
Description
timestamp (millisecondi dall'epoch) in cui l'attività è stata creata.
Un timestamp rappresenta il numero di millisecondi trascorsi dal 1° gennaio 1970 UTC, seguendo lo standard RFC 3339. Ad esempio, venerdì 1 settembre 2023 12:00:00 PM 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 l'attività ha iniziato l'elaborazione. 0 se non avviata.
Name
finished_at
Type
timestamp
Description
timestamp (millisecondi dall'epoch) in cui l'attività è terminata. 0 se non terminata.
Name
expires_at
Type
timestamp
Description
timestamp (millisecondi dall'epoch) in cui gli asset risultanti dell'attività scadono.
Name
task_error
Type
object
Description
Dettagli dell'errore per le attività non riuscite. Consulta Errori per il riferimento completo all'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questa attività. Presente quando lo stato dell'attività è PENDING, IN_PROGRESS o SUCCEEDED. Restituisce 0 per le attività FAILED (i crediti vengono rimborsati in caso di errore).
Name
result
Type
object
Description
Contiene gli URL dell'animazione di output se l'attività è 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 es., se è stata utilizzata l'operazione change_fps).
Name
preceding_tasks
Type
integer
Description
Il numero di attività precedenti nella 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
}