API di rigging

L'API di rigging consente di aggiungere programmaticamente uno scheletro (armatura) ai modelli umanoidi 3D, vincolando la mesh a esso in modo che siano pronti per l'animazione. Per applicare animazioni a un personaggio con rigging, consulta l'API di Animazione.

Tieni presente che attualmente il rigging programmatico funziona bene solo con asset umanoidi standard (bipedi) con arti e struttura corporea chiaramente definiti.

POST/openapi/v1/rigging

Crea un'attività di rigging

Questo endpoint consente di creare una nuova attività di rigging per un determinato modello 3D. Al completamento corretto, fornisce un personaggio con rig in formati standard e, opzionalmente, animazioni di camminata/corsa di base.

Attualmente, il rigging automatico non è adatto ai seguenti modelli:

Mesh senza texture
Asset non umanoidi
Asset umanoidi con struttura degli arti e del corpo poco chiara

Quando si usa input_task_id, i modelli con più di 300.000 facce non sono supportati per il rigging. Usa l'API Remesh per ridurre il numero di facce prima del rigging.

Quando si usa model_url, il volto del personaggio deve essere rivolto verso l'asse +Z (la direzione in avanti standard di glTF). I modelli rivolti verso altri assi causeranno il fallimento della stima della posa.

Parametri

È obbligatorio solo uno tra input_task_id e model_url. Se vengono forniti entrambi, input_task_id ha priorità.

Name
input_task_id
Type
string
Obbligatorio
Description
L'attività di input che deve essere sottoposta a rigging. Attualmente supportiamo modelli umanoidi con texture.

Name
model_url
Type
string
Obbligatorio
Description
Fornisci un modello 3D affinché Meshy possa eseguire il rigging tramite un URL accessibile pubblicamente o un Data URI. Attualmente supportiamo file GLB umanoidi con texture (formato .glb).

Name
height_meters
Type
number
predefinito 1.7
Description
L'altezza approssimativa del modello del personaggio in metri. Questo aiuta nella precisione del ridimensionamento e del rigging. Deve essere un numero positivo.
Name
texture_image_url
Type
string
Description
L'immagine texture del colore base del modello con UV unwrapped. URL accessibile pubblicamente o Data URI. Attualmente supportiamo i formati .png.

Restituisce

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

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante: deve essere fornito model_url oppure input_task_id.
- Formato del modello non valido: model_url punta a un file con un'estensione non supportata (supportato solo .glb).
- URL non raggiungibile: non è stato possibile scaricare model_url.
- Attività di input non valida: input_task_id non fa riferimento a un'attività API valida.
- Numero di facce superato: il modello di input ha più di 300.000 facce. Usa l'API Remesh per ridurre il numero di facce prima del rigging.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. Controlla la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questa attività.
Name
422 - Unprocessable Entity
Description
Stima della posa non riuscita. Il modello fornito potrebbe non essere un personaggio umanoide valido.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

GET/openapi/v1/rigging/:id

Recupera un'attività di rigging

Questo endpoint ti consente di recuperare un'attività di rigging dato un id attività valido. Consulta L'oggetto Rigging Task per vedere quali proprietà sono incluse.

Parametri

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

Restituisce

La risposta contiene l'oggetto Rigging Task. Consulta la sezione L'oggetto Rigging Task per i dettagli.

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/rigging/:id

Eliminare un'attività di rigging

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

Parametri del percorso

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

Restituisce

Restituisce 200 OK in caso di successo.

Request

DELETE

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/rigging/:id/stream

Eseguire lo streaming di un'attività di Rigging

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

Parametri

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

Restituisce

Restituisce uno stream di Oggetti dell'attività di Rigging come Server-Sent Events.

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

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/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": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Rigging Task Object structure
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  },
  "preceding_tasks": 0
}

L'oggetto Rigging Task

L'oggetto Rigging Task rappresenta l'unità di lavoro per il rigging di un personaggio.

Proprietà

Name
id
Type
string
Description
Identificatore univoco dell'attività.
Name
type
Type
string
Description
Tipo dell'attività di rigging. Il valore è rig.
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). 0 se non avviata, 100 se completata con successo.
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 e possono essere eliminati.
Name
task_error
Type
object
Description
Dettagli dell'errore per le attività non riuscite. Vedi 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 degli asset di output se l'attività è SUCCEEDED, altrimenti null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL scaricabile per il personaggio con rigging in formato FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL scaricabile per il personaggio con rigging in formato GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Contiene gli URL per le animazioni predefinite. (ad es. se generate_basic_animations era implicitamente true o abilitato per impostazione predefinita).
  Name
  walking_glb_url
  Type
  string
  Description
  URL scaricabile per l'animazione di camminata in formato GLB (con skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL scaricabile per l'animazione di camminata in formato FBX (con skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL scaricabile per l'armatura dell'animazione di camminata in formato GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL scaricabile per l'animazione di corsa in formato GLB (con skin).
  Name
  running_fbx_url
  Type
  string
  Description
  URL scaricabile per l'animazione di corsa in formato FBX (con skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL scaricabile per l'armatura dell'animazione di corsa in formato GLB.
Name
preceding_tasks
Type
integer
Description
Il numero di attività precedenti nella coda. Significativo solo se lo stato è PENDING.

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}