Ciclo di vita del task
Scopri come un task passa dalla richiesta al risultato, quanto tempo richiede in genere e per quanto tempo il tuo codice dovrebbe attenderlo.
Come viene eseguito un task
Una richiesta di creazione restituisce un ID di 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 stream, 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 campi created_at, started_at e finished_at.
La tabella seguente mostra cosa dovrebbe fare il tuo codice a ogni 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 periodo limitato. Vedi Conservazione degli asset. |
FAILED | Leggi task_error, quindi 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 finali. Dopo che un task raggiunge uno di questi stati, il suo stato non cambia più.
Dal punto di vista del tuo codice, la situazione è 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 in seguito usando lo stesso ID di task.Tempi di elaborazione
Le tabelle seguenti mostrano i tempi mediani sul traffico API di produzione nel settembre 2026.
Un tempo decorre dalla creazione del task fino allo stato finale. Quasi tutto questo tempo è elaborazione, perché un task rimane solitamente in PENDING solo per pochi secondi. Quando la coda è occupata, i task possono attendere più a lungo prima di iniziare, e i task sui piani con priorità più alta di solito iniziano 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 maggiore traffico, alcuni task richiedono più tempo e comunque riescono. Per controllare 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 tempo 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 questi 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.
Texturing
| 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 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 |
| Testo in movimento | 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 della mesh | 1 s |
| Controlli della mesh e delle pareti sottili | 10 s | |
| Multi-Color | Per richiesta | 30 s |
| Ripara stampabilità | Solo riparazione della mesh | 10 s |
| Controllo pareti sottili, pareti mantenute | 20 s | |
| Controllo pareti sottili, pareti ispessite | 100 s | |
| Auto Split | Parti a colore uniforme | 70 s |
Parti con texture (keep_texture: true) | 170 s |
Su v2, Ripara stampabilità e Analizza stampabilità eseguono sempre il controllo delle pareti sottili. Su v1, lo eseguono quando invii un tipo di stampante o una dimensione di stampa.
Quanto tempo attendere
Il task continua a essere eseguito anche se il tuo codice smette di attenderlo. 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, calcolati a partire dal
created_atdel task, prima di smettere di attendere. Se smetti prima, potresti perdere un task che riesce in un secondo momento. Questo accade soprattutto nei periodi di maggiore traffico. - Conserva l'ID del task. Puoi recuperare nuovamente il task in qualsiasi momento. Se non è ancora in uno stato finale dopo 60 minuti, controllalo di nuovo più tardi. Se rimane in quello stato, 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 oltre 100 MB | 120 secondi. Meshy scarica il file prima di rispondere. |
Timeout della richiesta di stato (GET) | 30 secondi |
| Intervallo di polling | L'header Retry-After, oppure 5 secondi se mancante. Le chiamate di polling contano ai fini del limite di frequenza. |
Richiesta di stato fallita (timeout, 429 o 5xx) | Riprova al polling successivo. 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.