Ciclo di vita del task
Scopri come un task passa dalla richiesta al risultato, quanto tempo richiede di solito e quanto a lungo il tuo codice dovrebbe attenderlo.
Come viene eseguito un task
Una richiesta di creazione restituisce un ID del task senza attendere che il task venga eseguito. Il task viene quindi eseguito in background e puoi seguirlo in uno dei tre modi seguenti: effettuare il polling del suo endpoint GET, aprire il suo endpoint di streaming oppure ricevere un webhook.
PENDING. Un worker lo prende in carico e passa a IN_PROGRESS, dove trascorre la maggior parte del tempo. Termina in SUCCEEDED o FAILED, e uno stato finale non cambia mai.PENDINGIN_PROGRESSSUCCEEDEDFAILEDIl task registra ogni fase nei suoi campi created_at, started_at e finished_at.
La tabella seguente mostra cosa dovrebbe fare il tuo codice per ciascuno stato.
| Stato | Cosa dovrebbe fare il tuo codice |
|---|---|
PENDING | Continua ad attendere. |
IN_PROGRESS | Monitora progress: la percentuale di lavoro completato, da 0 a 100. |
SUCCEEDED | Scarica il risultato. Meshy conserva i file per un tempo limitato. Vedi Conservazione degli asset. |
FAILED | Leggi task_error, poi correggi l'input o crea un nuovo task. Vedi Errori. |
CANCELED | Smetti di attendere. Il task non produrrà un risultato. Solo i task di Creative Lab usano questo stato. |
SUCCEEDED, FAILED e CANCELED sono stati finali. Dopo che un task raggiunge uno di questi stati, il suo stato non cambia più.
Dal punto di vista del tuo codice, la sequenza è questa:
Richiesta: POST/image-to-3d
Risposta: 202{ "result": "<task_id>" }task creato
- Ripeti ogni pochi secondi
Richiesta: GET/image-to-3d/<task_id>
Risposta: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5
Richiesta: GET/image-to-3d/<task_id>
Risposta: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }
GET più tardi con lo stesso ID del task.Tempi di elaborazione
Le tabelle seguenti mostrano i tempi mediani sul traffico API di produzione a settembre 2026.
Un tempo va dalla creazione del task allo stato finale. Quasi tutto il tempo è elaborazione, perché un task di solito rimane in PENDING solo per pochi secondi. Quando la coda è occupata, i task possono attendere più a lungo prima di avviarsi, e i task su piani con una priorità più alta di solito si avviano prima.
I tempi inferiori a 2 minuti sono espressi in secondi (s), mentre i tempi più lunghi sono espressi in minuti (min). "Non supportato" significa che l'API non offre quell'opzione con quel modello.
Questi sono tempi tipici, non tempi di completamento garantiti. Nei periodi di picco, alcuni task richiedono più tempo ma comunque vanno a buon fine. Per verificare lo stato di Meshy, consulta la pagina di stato. Non usare questi tempi come timeout nel tuo codice. Per i valori di timeout, vedi Quanto attendere.
Generazione 3D
| API | Configurazione | meshy-7.1 (latest) | meshy-6 | meshy-6-lite | meshy-t2 |
|---|---|---|---|---|---|
| Testo in 3D (Preview) | Solo mesh | 75 s | 90 s | 45 s | 10 s |
| Immagine in 3D | Solo mesh | 75 s | 90 s | 40 s | 4 s |
| Mesh con texture 2K | 2 min | 3 min | 75 s | 60 s | |
| Mesh con texture 4K | 2,5 min | 3,5 min | Non supportato | 80 s | |
| Mesh con texture 8K | 3,5 min | 4 min | Non supportato | 2,5 min | |
| Multi-immagine in 3D | Solo mesh | 65 s | 2 min | 30 s | Non supportato |
| Mesh con texture 2K | 2,5 min | 3,5 min | 85 s | Non supportato | |
| Mesh con texture 4K | 3 min | 4 min | Non supportato | Non supportato | |
| Mesh con texture 8K | 3,5 min | 4,5 min | Non supportato | Non supportato |
Per Immagine in 3D e Multi-immagine in 3D, "Solo mesh" significa should_texture: false. Queste opzioni e input modificano il tempo:
- Le mappe PBR (
enable_pbr) aggiungono da 30 a 60 secondi. - La geometria ultra (
geometry_resolution: "2k"o"4k") aggiunge fino a 1 minuto. - A parità di impostazioni, immagini di input più complesse richiedono più tempo.
Texturizzazione
| API | Risoluzione texture | Tempo tipico |
|---|---|---|
| Testo in 3D (Refine) | 2K o 4K | 80 s |
| 8K | 3,5 min | |
| Retexture | 2K | 55 s |
| 4K | 90 s | |
| 8K | 2,5 min |
Generazione di immagini
| API | nano-banana | nano-banana-2 | nano-banana-pro | Modelli GPT Image |
|---|---|---|---|---|
| Testo in immagine | 20 s | 15 s | 25 s | da 20 a 35 s |
| Immagine in immagine | 40 s | 20 s | 30 s | da 20 a 40 s |
Rigging e Animazione
| API | Configurazione | Tempo tipico |
|---|---|---|
| Auto-Rigging | Rigging automatico | 40 s |
| Animazione | Per richiesta | 15 s |
| Text to Motion | mode prime | 15 s |
mode swift | 10 s |
Post-elaborazione
| API | Tempo tipico |
|---|---|
| Remesh | 2 min |
| Unwrap UV | 35 s |
| Converti | 7 s |
| Ridimensiona | 15 s |
Stampa 3D
| API | Configurazione | Tempo tipico |
|---|---|---|
| Analizza stampabilità | Solo controlli sulla mesh | 1 s |
| Controlli su mesh e pareti sottili | 10 s | |
| Multi-Color | Per richiesta | 30 s |
| Ripara stampabilità | Solo riparazione mesh | 10 s |
| Controllo pareti sottili, pareti mantenute | 20 s | |
| Controllo pareti sottili, pareti ispessite | 100 s | |
| Auto Split | Per richiesta | 70 s |
Nella v2, Ripara stampabilità e Analizza stampabilità eseguono sempre il controllo delle pareti sottili. Nella v1, lo eseguono quando invii un tipo di stampante o una dimensione di stampa.
Quanto attendere
Il task continua a essere eseguito anche se il tuo codice smette di attendere. Se la tua richiesta va in timeout, la connessione si interrompe o lo stream si chiude, il task non fallisce e non viene annullato.
- Attendi almeno 60 minuti, contati dal
created_atdel task, prima di smettere di attendere. Se smetti prima, potresti perdere un task che va a buon fine in seguito. Questo accade soprattutto nei periodi di picco. - Conserva l'ID del task. Puoi recuperare il task in qualsiasi momento. Se non è ancora in uno stato finale dopo 60 minuti, controllalo di nuovo più tardi. Se la situazione persiste, contatta l'assistenza.
- Solo
FAILEDsignifica che il task è fallito. Meshy rimborsa automaticamente i task falliti.
Usa questi valori nel tuo codice:
| Impostazione | Valore consigliato |
|---|---|
Timeout della richiesta di creazione (POST) | 60 secondi |
Timeout della richiesta di creazione (POST) con un file model_url superiore a 100 MB | 120 secondi. Meshy scarica il file prima di rispondere. |
Timeout della richiesta di stato (GET) | 30 secondi |
| Intervallo di polling | L'intestazione Retry-After, oppure 5 secondi se manca. I poll contano ai fini del tuo limite di frequenza. |
Richiesta di stato fallita (timeout, 429 o 5xx) | Riprova al prossimo polling. Non significa che il task sia fallito. |
| Attesa complessiva per task | Almeno 60 minuti dal created_at. Non riavviare questo conteggio quando riconnetti uno stream. |
| Stream | Uno stream può chiudersi prima che il task termini. Se si chiude senza uno stato finale, riconnettiti o passa al polling. |
Per molti task contemporaneamente, usa i webhook invece di effettuare il polling di ciascuno. Se l'evento finale di un task non è arrivato dopo circa il doppio del suo tempo tipico, recupera il task dal suo endpoint GET.