Errori

Scopri perché una richiesta o un task è fallito, e cosa fare in seguito. Una richiesta può fallire immediatamente con un errore HTTP, mentre un task può fallire in seguito con un task_error.

Errori di richiesta

Meshy restituisce questi errori immediatamente, quando rifiuta una richiesta. Per scoprire cosa è andato storto, controlla il codice di stato HTTP e il campo message.

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

Errori del task

Un task creato da Meshy può comunque fallire durante l'esecuzione. Il suo status diventa FAILED, Meshy rimborsa i suoi crediti e task_error spiega il motivo.

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

type è la categoria generale del fallimento. Usalo per decidere cosa fare dopo.

Codici di errore

Quando code è presente, indica uno dei seguenti problemi.

image_too_complex

L'immagine di input o il prompt descrive un soggetto geometricamente troppo complesso per la generazione 3D.

Ad esempio:

• Mucchi densi di piccoli oggetti, come una cassa piena di frutta o una pila di libri
• Motivi ripetitivi intricati, come strutture reticolari, impalcature o reti metalliche
• Edifici complessi, come edifici a più piani con molte finestre e balconi
• Diversi oggetti distinti in un'unica immagine, invece di un singolo soggetto

Questi input sono probabilmente troppo complessi:

Per risolvere il problema, prova uno o più dei seguenti suggerimenti:

• Usa un solo oggetto per immagine. Meshy funziona al meglio con un unico soggetto chiaro, quindi non inserire più oggetti separati nella stessa immagine o nello stesso prompt.
• Semplifica il tuo soggetto. Ad esempio, usa un semplice vaso invece di un vaso pieno di decine di fiori.
• Evita le scene. Interi edifici, isolati cittadini, stanze arredate e paesaggi sono probabilmente troppo complessi. Concentrati su un singolo oggetto.
• Evita strutture dense e ripetitive. Impalcature, reti metalliche, strutture reticolari e mucchi di piccoli oggetti sono cause comuni.

model_missing_uv

Hai inviato 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.

Per risolvere il problema, fai una delle seguenti operazioni:

• Per mantenere il layout UV del tuo modello, ad esempio per un posizionamento personalizzato delle cuciture, aggiungi le UV al modello nel tuo software 3D. Controllale nel suo editor UV, quindi carica di nuovo il modello. I file STL non possono memorizzare le UV, quindi usa GLB, FBX o OBJ.
• Se non ti serve un layout personalizzato, o non sei sicuro, ometti enable_original_uv oppure impostalo su false. Meshy creerà quindi un layout UV per il modello. Le nuove UV coprono bene il modello, ma non puoi controllare dove vadano le cuciture della texture.

model_insufficient_uv

Il modello ha coordinate UV, ma coprono troppo poco dello spazio UV per essere texturizzato correttamente. Questo accade spesso con modelli il cui esportatore ha scritto UV segnaposto o collassate senza un corretto unwrap.

Per risolvere il problema, effettua una delle seguenti operazioni:

• Per mantenere il tuo layout UV, esegui nuovamente l'unwrap delle UV del modello nel tuo software 3D. Distribuisci le isole su tutto lo spazio UV invece che in un piccolo angolo di esso.
• Se non hai bisogno di un tuo layout, ometti enable_original_uv oppure impostalo su false. Meshy creerà quindi un nuovo layout UV. Perderai il posizionamento delle tue cuciture, ma le nuove UV copriranno spazio sufficiente per la texturizzazione.

model_missing_texture

Il modello di input di un'attività di Multi-Color Print non ha alcun colore che Meshy possa suddividere in colori di stampa. Meshy costruisce un 3MF multicolore a partire dai colori del modello, quindi una mesh bianca uniforme non offre nulla su cui lavorare. Ad esempio, un'anteprima Testo in 3D o Immagine in 3D che non è mai stata texturizzata non ha colore. Lo stesso vale per l'output di Ripara stampabilità, o per un'attività Auto Split che non ha mantenuto la texture.

Ciò che conta come colore dipende dallo style richiesto:

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

Meshy rifiuta un modello privo sia di texture del colore base che di colori dei vertici per entrambi gli stili, invece di lasciare che cartoon lo trasformi in una stampa monocolore.

Meshy rifiuta la maggior parte di queste richieste prima ancora di creare l'attività, restituendo un 400 con la stessa spiegazione. Di solito si ottiene questo codice solo quando Meshy non può controllare l'input in anticipo. Ad esempio, Meshy controlla un caricamento .fbx solo dopo che l'attività lo ha convertito.

Per risolvere il problema, usa l'opzione adatta al tuo modello:

• Applica prima la texture al modello. Esegui Retexture su di esso, oppure generalo con un'attività refine di Testo in 3D o un'attività di Immagine in 3D con should_texture: true. Quindi invia quell'attività come input_task_id.
• Per un modello con colori per vertice, come una scansione fotogrammetrica o una mesh dipinta a mano, usa style: "cartoon", che legge COLOR_0.
• Per un modello parzialmente texturizzato o multi-texture con realistic, assegna a ogni parte della mesh le UV e la stessa unica texture del colore base. Per farlo, applica la texture alle parti rimanenti, oppure unisci le texture in un unico atlas. Puoi anche passare a style: "cartoon".

textured_split_refused

Un task di Auto Split con keep_texture: true non riesce a mantenere la texture del modello di input sulle parti. Ad esempio, il modello non ha UV, oppure la sua texture non ha spazio per le nuove facce create dai tagli. Meshy rimborsa i crediti.

Per risolvere il problema, invia nuovamente la richiesta senza keep_texture, oppure con keep_texture: false. Le parti verranno quindi restituite ciascuna con un colore uniforme.

invalid_input

L'input non ha superato un controllo e non si applica nessun codice più specifico. message indica il motivo.

Ad esempio:

• Un file del modello vuoto o danneggiato
• Una variante non supportata di un formato di file, come un file FBX ASCII o un file GLB compresso con meshopt
• Un modello caricato privo di oggetti 3D validi, ad esempio un file contenente solo armature, telecamere o luci
• Contenuto che non supera i filtri di sicurezza

Per risolvere il problema, leggi message per individuare il problema specifico. Verifica che i file di input e i parametri soddisfino i requisiti dell'endpoint.

moderation_blocked

I filtri di sicurezza hanno rifiutato il tuo prompt o le immagini di riferimento. I filtri controllano il testo e le immagini insieme.

Per risolvere il problema, esegui una o entrambe le azioni seguenti:

• Riformula il prompt per rimuovere descrizioni allusive o sensibili.
• Cambia le immagini di riferimento che mostrano contenuti che i filtri potrebbero bloccare.

moderation_unavailable

Tipo: server_error. La moderation dei contenuti era temporaneamente non disponibile, quindi Meshy ha fatto fallire l'attività invece di saltare il controllo. Non c'è nulla che non va nel tuo contenuto.

Per risolvere il problema, crea di nuovo l'attività.

timeout

Il task ha superato un limite di tempo lato server, per l'elaborazione o per l'attesa in coda, quindi Meshy lo ha segnato come fallito e ha rimborsato i crediti. Un carico elevato, oppure un input troppo complesso da completare in tempo, possono causarlo.

Questo è diverso da un timeout nel tuo codice. Se il tuo client ha smesso di attendere, il task è comunque ancora in esecuzione. Vedi Quanto tempo attendere.

Per risolverlo, segui questi passaggi:

1. Crea di nuovo il task. I timeout sono spesso temporanei, e un nuovo task potrebbe avere successo.
2. Se continua a fallire, semplifica il tuo input, ad esempio riducendo il livello di dettaglio della tua immagine o del tuo prompt. Per gli input più difficili da elaborare, vedi image_too_complex.

queue_timeout

Tipo: timeout. L'attività è rimasta in coda troppo a lungo senza avviarsi, quindi Meshy l'ha contrassegnata come non riuscita e ha restituito eventuali crediti addebitati per essa. Il tuo input non ha causato questo errore.

Per risolvere il problema, crea nuovamente l'attività.

format_conversion_failed

Meshy ha generato il modello, ma la conversione in un formato richiesto non è riuscita.

Per risolvere il problema, segui questi passaggi:

1. Crea nuovamente l'attività.
2. Se un formato continua a non funzionare, richiedi un formato diverso che soddisfi le tue esigenze.

Best practices

• Esegui nuovamente i task falliti. Per un task fallito con timeout, service_unavailable o server_error, crea un nuovo task con backoff esponenziale.
• Non creare un nuovo task quando è la tua richiesta a scadere per timeout. Il primo task potrebbe essere ancora in esecuzione, quindi verifica se esiste prima di crearne un altro. Consulta Quanto tempo attendere.
• Registra gli ID dei task. Includi l'ID quando contatti l'assistenza.
• Controlla gli input prima di inviarli. Assicurati che immagini e modelli soddisfino i requisiti di formato dell'endpoint.
• Chiama l'API dal tuo server. Il codice eseguito in un browser espone la tua chiave API a chiunque apra la pagina.