API di Rigging

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

Si prega di notare che il rigging programmato attualmente funziona bene solo con asset umanoidi standard (bipedi) con arti e struttura corporea chiaramente definiti in questo momento.

POST/openapi/v1/rigging

Creare un Task di Rigging

Questo endpoint ti permette di creare un nuovo task di rigging per un dato modello 3D. Al completamento con successo, fornisce un personaggio riggato in formati standard e opzionalmente animazioni di base di camminata/corsa.

Attualmente, l'auto-rigging non è adatto per i seguenti modelli:

Mesh non texturizzate
Asset non umanoidi
Asset umanoidi con struttura degli arti e del corpo non chiara

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

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

Parametri

Solo uno tra input_task_id o model_url è richiesto. Se entrambi sono forniti, input_task_id ha la priorità.

Name
input_task_id
Type
string
Obbligatorio
Description
Il task di input che deve essere riggato. Attualmente supportiamo modelli umanoidi texturizzati.

Name
model_url
Type
string
Obbligatorio
Description
Si prega di fornire un modello 3D per Meshy da riggare tramite un URL pubblicamente accessibile o Data URI. Attualmente supportiamo file GLB umanoidi texturizzati (formato .glb).

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

Restituzioni

La proprietà result della risposta contiene l'id del task di rigging appena creato.

Modalità di Fallimento

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante: Devono essere forniti model_url o input_task_id.
- Formato modello non valido: Il model_url punta a un file con un'estensione non supportata (solo .glb supportato).
- URL irraggiungibile: Il model_url non può essere scaricato.
- Task di input non valido: Il input_task_id non si riferisce a un task API valido.
- Numero di facce superato: Il modello di input ha più di 300.000 facce. Si prega di utilizzare l'API di Remesh per ridurre il numero di facce prima del rigging.
Name
401 - Unauthorized
Description
Autenticazione fallita. Si prega di controllare la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questo task.
Name
422 - Unprocessable Entity
Description
La stima della posa è fallita. 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 Task di Rigging

Questo endpoint ti permette di recuperare un task di rigging dato un valido id del task. Consulta L'Oggetto Task di Rigging per vedere quali proprietà sono incluse.

Parametri

Name
id
Type
path
Description
Identificatore univoco per il task di rigging da recuperare.

Restituisce

La risposta contiene l'oggetto Task di Rigging. Controlla la sezione L'Oggetto Task di Rigging per i dettagli.

Richiesta

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

Risposta

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

Elimina un'attività di rigging

Questo endpoint elimina permanentemente 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.

Richiesta

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

Risposta

// Returns 200 Ok on success.

GET/openapi/v1/rigging

Elenco delle attività di rigging

Restituisce un elenco paginato delle attività di rigging dell'utente, dalla più recente. Paginazione standard tramite page_num e page_size.

Nota che le attività create tramite l'API sono gestite tramite l'API — non appaiono in I miei asset dell'app web. Usa questo endpoint per trovare un'attività di cui non hai più l'ID.

Richiesta

GET

/openapi/v1/rigging

curl "https://api.meshy.ai/openapi/v1/rigging?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

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

Trasmetti un'attività di Rigging

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

Parametri

Name
id
Type
path
Description
Identificatore univoco per l'attività di Rigging da trasmettere.

Restituisce

Restituisce un flusso di Gli Oggetti dell'Attività di Rigging come Server-Sent Events.

Per attività PENDING o IN_PROGRESS, il flusso di risposta includerà solo i campi necessari progress e status.

Richiesta

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 Task di Rigging

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

Proprietà

Name
id
Type
string
Description
Identificatore univoco per il task.
Name
type
Type
string
Description
Tipo del task di Rigging. Il valore è rig.
Name
status
Type
string
Description
Stato del task. Valori possibili: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso del task (0-100). 0 se non avviato, 100 se completato con successo.
Name
created_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoca) quando il task è stato creato.
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 nell'API di Meshy.
Name
started_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoca) quando il task ha iniziato l'elaborazione. 0 se non avviato.
Name
finished_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoca) quando il task è terminato. 0 se non terminato.
Name
expires_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoca) quando gli asset di risultato del task scadono e possono essere eliminati.
Name
task_error
Type
object
Description
Dettagli dell'errore per i task falliti. Vedi Errori per il riferimento completo all'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 degli asset di output se il task SUCCEEDED, null altrimenti.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL scaricabile per il personaggio riggato in formato FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL scaricabile per il personaggio riggato in formato GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Contiene gli URL per le animazioni predefinite. (ad esempio se generate_basic_animations era implicitamente vero o abilitato di default).
  Name
  walking_glb_url
  Type
  string
  Description
  URL scaricabile per l'animazione di camminata in formato GLB (con pelle).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL scaricabile per l'animazione di camminata in formato FBX (con pelle).
  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 pelle).
  Name
  running_fbx_url
  Type
  string
  Description
  URL scaricabile per l'animazione di corsa in formato FBX (con pelle).
  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 conteggio dei task 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
}