Errori

In questa guida parleremo di cosa succede quando qualcosa va storto mentre lavori con la Meshy API.

Errori della richiesta

Questi errori vengono restituiti immediatamente quando la tua richiesta API viene rifiutata. Controlla il codice di stato HTTP e il campo message per capire cosa è andato storto.

{
  "message": "Invalid model file extension: .3dm"
}

Errori delle attività

Questi errori si verificano dopo che un'attività è stata creata ed è in elaborazione. Controlla l'oggetto task_error nella risposta dell'attività per i dettagli dell'errore.

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

Tipi di errore

Il campo type indica la categoria generale dell'errore. Usalo per decidere la tua strategia di nuovo tentativo.

Codici di errore

Quando il campo code è presente, identifica un problema specifico e risolvibile. Di seguito è riportato il riferimento completo per ciascun codice di errore.

image_too_complex

Questo errore si verifica quando l'immagine di input o il prompt descrive un soggetto troppo complesso dal punto di vista geometrico perché il modello di generazione 3D possa elaborarlo.

Esempi comuni includono:

• Cumuli densi di piccoli oggetti (ad es., una cassetta piena di frutta, una pila di libri)
• Pattern ripetitivi intricati (ad es., strutture a reticolo, impalcature, mesh metalliche)
• Strutture edilizie complesse (ad es., edifici a più piani con molte finestre e balconi)
• Più oggetti distinti in un'unica immagine invece di un singolo soggetto

Esempi di input che sono probabilmente troppo complessi:

Risoluzione:

1. Usa un singolo oggetto per immagine. Il modello funziona al meglio con un soggetto chiaro. Non includere più oggetti separati nella stessa immagine o nello stesso prompt.
2. Semplifica il soggetto. Riduci il livello di dettaglio. Ad esempio, un vaso semplice invece di un vaso riempito con decine di fiori.
3. Evita prompt a livello di scena. Interi edifici, isolati urbani, interni pieni di mobili o paesaggi probabilmente supereranno la capacità del modello. Concentrati invece su un singolo oggetto.
4. Evita strutture ripetitive dense. Soggetti come impalcature, mesh metalliche, pattern a reticolo o cumuli di molti piccoli elementi sono trigger comuni.

model_missing_uv

Questo errore si verifica quando carichi un modello per la texturizzazione con enable_original_uv impostato su true, ma il modello non ha coordinate UV. Le coordinate UV definiscono come una texture 2D si avvolge sulla superficie 3D del tuo modello.

Risoluzione:

La correzione appropriata dipende dal motivo per cui hai impostato enable_original_uv su true:

• Se devi preservare il layout UV originale del tuo modello (ad es., posizionamento personalizzato delle cuciture per una mappatura precisa della texture): il tuo modello deve avere coordinate UV valide. Verifica che le UV esistano nell'editor UV del tuo software 3D prima del caricamento. Nota che i file STL non possono memorizzare dati UV, quindi usa invece GLB, FBX o OBJ.
• Se non hai bisogno di un controllo UV specifico (o non ne sei sicuro): ometti enable_original_uv o impostalo su false. Il sistema genererà automaticamente un layout UV per il tuo modello. Le UV generate automaticamente sono ottimizzate per la copertura, ma non avrai controllo su dove vengono posizionate le cuciture della texture.

model_insufficient_uv

Questo errore si verifica quando un modello ha coordinate UV, ma la copertura UV è troppo ridotta per una texturizzazione di qualità. Questo accade comunemente con modelli esportati da strumenti 3D che generano UV segnaposto o collassate senza un unwrap adeguato.

Risoluzione:

• Se devi preservare il tuo layout UV originale: esegui nuovamente l'unwrap delle UV del modello nel tuo software 3D. Assicurati che le isole UV siano distribuite correttamente nello spazio UV invece di essere collassate in una piccola area.
• Se non hai bisogno di un controllo UV specifico: ometti enable_original_uv oppure impostalo su false. Il sistema genererà automaticamente un nuovo layout UV. Il compromesso è che perdi il posizionamento originale delle cuciture, ma le UV generate automaticamente avranno una copertura adeguata per la texturizzazione.

invalid_input

Questo è il codice di errore di fallback quando l'input non supera la validazione ma non si applica alcun codice più specifico. Il campo message contiene il motivo specifico dell'errore.

Le cause comuni includono:

• File di modello vuoti o corrotti
• Varianti di formato file non supportate (ad es., file FBX ASCII, GLB compressi con meshopt)
• Nessun oggetto 3D valido trovato nel modello caricato (ad es., il file contiene solo armature, camere o luci)
• Contenuti che non superano i filtri di sicurezza

Risoluzione: Controlla il campo message per dettagli su cosa è andato storto. Verifica che i tuoi file di input e parametri corrispondano ai requisiti dell'endpoint.

moderation_blocked

Questo errore si verifica quando il tuo prompt o le immagini di riferimento vengono rifiutati dai filtri di sicurezza dell'AI. Il filtro valuta insieme sia il prompt testuale sia eventuali immagini di riferimento.

Risoluzione:

• Riformula il tuo prompt testuale per rimuovere descrizioni suggestive o sensibili.
• Modifica le immagini di riferimento se raffigurano contenuti che potrebbero attivare i filtri di sicurezza.

timeout

Questo errore significa che il tempo di elaborazione del tuo task ha superato il limite consentito. Questo può accadere a causa di un carico elevato del sistema o perché l'input è troppo complesso da elaborare entro il limite di tempo.

Risoluzione:

1. Riprova la richiesta. I timeout sono spesso transitori e un nuovo tentativo potrebbe riuscire.
2. Semplifica il tuo input. Se i nuovi tentativi continuano a fallire, il tuo input potrebbe essere troppo complesso. Prova a ridurre il livello di dettaglio nella tua immagine o nel prompt. Consulta image_too_complex per indicazioni sui tipi di input più difficili da elaborare.

format_conversion_failed

Questo errore si verifica quando il modello 3D generato non ha potuto essere convertito nel formato di output richiesto. Il modello è stato generato correttamente, ma il passaggio di conversione non è riuscito.

Risoluzione:

1. Riprova la richiesta.
2. Prova un formato di output diverso. Se un formato specifico continua a non riuscire, passa a un altro formato adatto alle tue esigenze.

Procedure consigliate

1. Implementa la logica di retry. Per gli errori timeout e service_unavailable, implementa una logica di retry con backoff esponenziale.
2. Registra gli ID delle attività. Registra sempre l'ID dell'attività a fini di debug. Includilo quando contatti il supporto.
3. Convalida gli input. Assicurati che le immagini e i modelli di input soddisfino i requisiti di formato prima dell'invio.