Errori

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

Errori di 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 del Task

Questi errori si verificano dopo che un task è stato creato ed è in elaborazione. Controlla l'oggetto task_error nella risposta del task 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 del fallimento. Usalo per decidere la tua strategia di ritentativo.

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 geometricamente per essere elaborato dal modello di generazione 3D.

Esempi comuni includono:

• Pile dense di piccoli oggetti (ad es., una cassa piena di frutta, una pila di libri)
• Motivi intricati e ripetuti (ad es., strutture a griglia, impalcature, reti metalliche)
• Strutture edilizie complesse (ad es., edifici a più piani con molte finestre e balconi)
• Molteplici oggetti distinti in un'immagine invece di un singolo soggetto

Esempi di input probabilmente troppo complessi:

Risoluzione:

1. Usa un singolo oggetto per immagine. Il modello funziona meglio con un soggetto chiaro. Non includere più oggetti separati nella stessa immagine o prompt.
2. Semplifica il tuo soggetto. Riduci il livello di dettaglio. Ad esempio, un semplice vaso invece di un vaso pieno di dozzine di fiori.
3. Evita prompt a livello di scena. Edifici interi, isolati di città, interni pieni di mobili o paesaggi probabilmente superano la capacità del modello. Concentrati su un singolo oggetto invece.
4. Evita strutture ripetute dense. Soggetti come impalcature, reti metalliche, motivi a griglia o pile di molti piccoli oggetti sono comuni fattori scatenanti.

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 soluzione giusta dipende dal motivo per cui hai impostato enable_original_uv su true:

• Se hai bisogno di preservare il layout UV originale del tuo modello (ad esempio, posizionamento personalizzato delle cuciture per una mappatura precisa delle texture): il tuo modello deve avere coordinate UV valide. Verifica che le UV esistano nell'editor UV del tuo software 3D prima di caricare. Nota che i file STL non possono memorizzare dati UV, quindi utilizza GLB, FBX o OBJ invece.
• Se non hai bisogno di un controllo specifico sulle UV (o non 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 delle texture.

model_insufficient_uv

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

Risoluzione:

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

model_missing_texture

Questo errore si verifica quando il modello di input di un task di Multi-Color Print non ha informazioni sul colore che il convertitore possa separare in colori di stampa. Un 3MF multicolore viene costruito a partire dai colori del modello, quindi una mesh completamente bianca — ad esempio un'anteprima Testo in 3D o Immagine in 3D mai texturizzata, oppure un output riparato / suddiviso automaticamente — non offre nulla su cui lavorare.

Ciò che conta come fonte di colore dipende dallo style richiesto:

• realistic campiona la texture del colore base attraverso le coordinate UV del modello, quindi richiede un'unica texture del colore base con coordinate UV su ogni parte della mesh.
• cartoon appiattisce i colori per faccia e accetta una texture del colore base su qualsiasi parte oppure colori per vertice (COLOR_0).

Un modello privo sia di texture del colore base che di colori per vertice viene rifiutato per entrambi gli style; con cartoon, altrimenti, "riuscirebbe" come stampa a colore singolo.

La maggior parte delle richieste viene rifiutata prima ancora che il task venga creato (400 Bad Request con la stessa spiegazione), quindi in genere vedrai questo codice solo quando l'input non poteva essere ispezionato in anticipo — un caricamento .fbx, ad esempio, viene controllato una volta che il task lo ha normalizzato.

Risoluzione:

• Applica prima la texture al modello. Esegui un task di Retexture su di esso, oppure generalo con la texturizzazione abilitata (un task refine di Testo in 3D, o un task di Immagine in 3D con should_texture: true), e passa quel task come input_task_id.
• Modelli con colori per vertice (scansioni fotogrammetriche, mesh dipinte a mano): richiedi style: "cartoon", che legge COLOR_0.
• Modelli parzialmente texturizzati o multi-texture con realistic: ogni parte della mesh necessita di coordinate UV e della stessa, unica texture del colore base. Applica la texture alle parti rimanenti oppure unisci le texture in un unico atlas, oppure passa a style: "cartoon".

invalid_input

Questo è il codice di errore di fallback quando l'input non supera la validazione ma non si applica nessun codice più specifico. Il campo message contiene la ragione specifica del fallimento.

Cause comuni includono:

• File di modelli vuoti o corrotti
• Variazioni di formato file non supportate (ad esempio, file FBX ASCII, GLB compressi con meshopt)
• Nessun oggetto 3D valido trovato nel modello caricato (ad esempio, il file contiene solo armature, telecamere 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 AI. Il filtro valuta sia il prompt di testo che eventuali immagini di riferimento insieme.

Risoluzione:

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

timeout

Questo errore significa che il tempo di elaborazione del tuo compito ha superato il limite consentito. Questo può accadere a causa di un elevato carico di 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 avere successo.
2. Semplifica il tuo input. Se i tentativi continuano a fallire, il tuo input potrebbe essere troppo complesso. Prova a ridurre il livello di dettaglio nella tua immagine o nel tuo prompt. Vedi image_too_complex per indicazioni su quali tipi di input sono più difficili da elaborare.

format_conversion_failed

Questo errore si verifica quando il modello 3D generato non può essere convertito nel formato di output richiesto. Il modello è stato generato con successo, ma il passaggio di conversione è fallito.

Risoluzione:

1. Riprova la richiesta.
2. Prova un formato di output diverso. Se un formato specifico continua a fallire, passa a un altro formato che soddisfi le tue esigenze.

Migliori Pratiche

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