Rigging API

Aggiungi uno scheletro (armatura) a un modello 3D umanoide e collega la mesh ad esso, in modo che il personaggio sia pronto per l'animazione. Per applicare animazioni a un personaggio con rig, consulta l'Animation API.

Il rigging funziona bene solo con personaggi umanoidi standard (bipedi) che hanno una struttura degli arti e del corpo chiaramente definita.

POST/openapi/v1/rigging

Crea un task di Rigging

Crea un task di Rigging per un modello 3D. Quando il task ha esito positivo, restituisce un personaggio con rig in formati standard e, facoltativamente, animazioni di base di camminata e corsa.

Il task viene eseguito in background. Per sapere quanto dura di solito un task, consulta Tempi di elaborazione.

Il rigging non è adatto per questi modelli:

Mesh senza texture
Asset non umanoidi
Asset umanoidi con una struttura di arti e corpo poco chiara

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

Parametri

Name
input_task_id
Type
string
Obbligatorio
Description
Obbligatorio a meno che tu non invii model_url. L'ID del task il cui modello vuoi sottoporre a rigging. Meshy supporta modelli umanoidi texturizzati.
Il modello può avere al massimo 380.000 triangoli (un quad conta come 2), e un modello con un numero maggiore restituisce 400. Per rimanere sotto il limite, esegui prima la Remesh API con un target_polycount di 300000 o inferiore, oppure 150000 o inferiore con topology: quad.

Name
model_url
Type
string
Obbligatorio
Description
Obbligatorio a meno che tu non invii input_task_id. Il modello da sottoporre a rigging, come URL pubblico o data URI. Se invii entrambi, Meshy usa input_task_id.
Il modello deve essere un file GLB (.glb) di al massimo 400 MB da un URL http o https, oppure 100 MB come data URI. Il rigging supporta modelli umanoidi texturizzati.
Il modello può avere al massimo 380.000 triangoli (un quad conta come 2), e un modello con un numero maggiore restituisce 400. Per rimanere sotto il limite, esegui prima la Remesh API con un target_polycount di 300000 o inferiore, oppure 150000 o inferiore con topology: quad.
Il volto del personaggio deve essere rivolto verso l'asse +Z, la direzione frontale standard di glTF. La stima della posa fallisce per un modello rivolto verso un altro asse.
Un file oltre i 100 MB deve inoltre rispettare queste regole:
- Può avere al massimo 10.000.000 di facce. Un file con un numero maggiore restituisce 400. Meshy conta le facce come triangoli, e una mesh disegnata più di una volta conta una volta per copia.
- Non deve utilizzare la compressione Draco.

Name
height_meters
Type
number
predefinito 1.7
Description
L'altezza approssimativa del personaggio, in metri. Meshy la usa per scalare e sottoporre a rigging il modello in modo più accurato. Un valore negativo restituisce 400.
Name
texture_image_url
Type
string
⚠ deprecato
Description
Omettilo quando il modello ha le proprie texture. Senza di esso, Meshy usa le texture incorporate nel file model_url, oppure le texture del task di input. Se lo invii, questa immagine diventa l'unica texture del modello sottoposto a rigging, e il modello perde le sue mappe PBR.
La texture base unwrapped UV del modello, come URL pubblico o data URI. L'immagine deve essere un file PNG di al massimo 20 MB. Un altro formato di immagine restituisce 400.

Restituisce

Il campo result della risposta contiene l'ID del nuovo task di Rigging.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Il messaggio di errore indica quale problema è stato rilevato. Ad esempio:
- Parametro mancante: Non è stato inviato né model_url né input_task_id.
- Formato del modello non valido: Il file model_url ha un'estensione non supportata. È supportato solo .glb.
- URL non raggiungibile: Meshy non riesce a scaricare il file model_url.
- File del modello troppo grande: Il file model_url supera i 400 MB da un URL http o https, oppure i 100 MB come data URI.
- Troppe facce: Il file model_url supera i 100 MB e ha più di 10.000.000 di facce. Riduci il numero di facce, poi invia nuovamente il file.
- File del modello illeggibile: Il file model_url supera i 100 MB, e Meshy non riesce a leggerne l'intestazione. Ad esempio, è un file GLB compresso con Draco.
- Intestazione del modello troppo complessa: Il file model_url supera i 100 MB, e la sua intestazione ha troppe mesh, nodi o record da verificare. Riduci il numero di oggetti nel file, poi inviarlo nuovamente.
- Immagine troppo grande: L'immagine texture_image_url supera i 20 MB.
- Formato texture non valido: L'immagine texture_image_url non è un file PNG.
- Altezza non valida: height_meters è negativo.
- Task di input non valido: input_task_id non fa riferimento a un task API valido.
- Numero di facce superato: Il modello di input ha più di 380.000 triangoli (un quad conta come 2). Esegui la Remesh API con un target_polycount di 300000 o inferiore, oppure 150000 o inferiore con topology: quad, prima di sottoporre il modello a rigging.
Correggi la richiesta, poi inviala nuovamente. Consulta 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, poi riprova.
- Piano gratuito: La creazione di un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, poi riprova.
Name
403 - Forbidden
Description
input_task_id è un modello bassorilievo, che questo endpoint non può sottoporre a rigging. Il messaggio è This model type does not support this operation. Invia un modello diverso.
Name
422 - Unprocessable Entity
Description
La stima della posa non è riuscita. Il modello potrebbe non essere un personaggio umanoide valido. Invia un modello di un personaggio umanoide. Per model_url, verifica anche che il personaggio sia rivolto verso l'asse +Z.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza. Attendi, poi riprova. Consulta Limiti di frequenza.

GET/openapi/v1/rigging/:id

Recupera un task di Rigging

Restituisce un task di Rigging tramite il suo ID.

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
}

Parametri

Name
id
Type
path
Description
L'ID del task dalla risposta di creazione.

Restituisce

L'oggetto task di Rigging.

DELETE/openapi/v1/rigging/:id

Elimina un task di Rigging

Elimina definitivamente un task di Rigging, inclusi i suoi modelli e dati. Non è possibile annullare un'eliminazione.

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

// 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 del task da eliminare.

Stato del task

Eliminare un task PENDING rimborsa i crediti utilizzati al momento della sua creazione.

Un task IN_PROGRESS non può essere eliminato. La richiesta restituisce 409 Conflict, e il task continua a essere eseguito. Meshy non rimborsa un task che è già iniziato, quindi eliminarlo ti farebbe perdere sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminalo.

Eliminare un task in uno stato finale (SUCCEEDED, FAILED o CANCELED) non rimborsa i suoi crediti.

Restituisce

200 OK quando il task viene eliminato, oppure 409 Conflict quando il task è IN_PROGRESS.

GET/openapi/v1/rigging

Elenco dei task di Rigging

Restituisce un elenco paginato dei tuoi task di Rigging, dal più recente al meno recente. Per scorrere l'elenco, utilizza page_num e page_size.

I task creati tramite l'API restano nell'API e non compaiono in My Assets nell'app web. Per trovare un task di cui non hai più l'ID, utilizza questo endpoint.

Request

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

Esegui lo streaming di un'attività di Rigging

Trasmette in streaming gli aggiornamenti di un'attività di Rigging come Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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 event, with the same fields as the 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/.../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
}

Parametri

Name
id
Type
path
Description
L'ID dell'attività proveniente dalla risposta di creazione.

Valori restituiti

Uno stream di oggetti attività di Rigging come Server-Sent Events.

Ogni evento contiene l'oggetto attività completo, nello stesso formato restituito dall'endpoint Get. Mentre l'attività è PENDING o IN_PROGRESS, i suoi campi di risultato non hanno ancora valori.

L'oggetto task di Rigging

Un oggetto task di Rigging descrive il rigging di un personaggio. Contiene lo stato, il progress e i file di output quando il task ha successo.

Proprietà

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
}

Name
id
Type
string
Description
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 rig.
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 è stato completato, come 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 in cui il task è iniziato, in millisecondi Unix. È 0 finché il task non inizia.
Name
finished_at
Type
timestamp
Description
Ora in cui il task è terminato, in millisecondi Unix. È 0 finché il task non termina.
Name
expires_at
Type
timestamp
Description
Ora in cui i file di risultato del task scadono, in millisecondi Unix. Dopo questo momento, Meshy può eliminare i file.
Name
task_error
Type
object
Description
I dettagli dell'errore quando il task fallisce. Vedi Errori.
Name
consumed_credits
Type
integer
Description
Il numero di crediti utilizzati 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
Gli URL dei file di output. Finché il task non ha successo, ogni URL è una stringa vuota e basic_animations è null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL di download per il personaggio con rig come file FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL di download per il personaggio con rig come file GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  URL di download per le animazioni predefinite di camminata e corsa.
  Name
  walking_glb_url
  Type
  string
  Description
  L'animazione di camminata con skin, come file GLB.
  Name
  walking_fbx_url
  Type
  string
  Description
  L'animazione di camminata con skin, come file FBX.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  L'armatura dell'animazione di camminata, come file GLB.
  Name
  running_glb_url
  Type
  string
  Description
  L'animazione di corsa con skin, come file GLB.
  Name
  running_fbx_url
  Type
  string
  Description
  L'animazione di corsa con skin, come file FBX.
  Name
  running_armature_glb_url
  Type
  string
  Description
  L'armatura dell'animazione di corsa, come file GLB.
Name
preceding_tasks
Type
integer
Description
Il numero di task davanti a questo nella coda. Il valore è significativo solo mentre il task è PENDING.