lowpoly verrà ritirato il 30 ott 2026. meshy-7 come modello di generazione 3D verrà ritirato il 31 dic 2026; come modello di texture resta disponibile. Cambia modello prima di queste date per evitare errori nelle richieste. Vedi tutte le deprecazioni

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.

Una richiesta di creazione avvia un task in 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.
Richiesta di creazione
PENDING
In attesa nella coda
IN_PROGRESS
Generazione del risultato
SUCCEEDED
Scarica il risultato
FAILED
Crediti rimborsati

Il 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.

StatoCosa dovrebbe fare il tuo codice
PENDINGContinua ad attendere.
IN_PROGRESSMonitora progress: la percentuale di lavoro completato, da 0 a 100.
SUCCEEDEDScarica il risultato. Meshy conserva i file per un periodo limitato. Vedi Conservazione degli asset.
FAILEDLeggi task_error, quindi correggi l'input o crea un nuovo task. Vedi Errori.
CANCELEDSmetti 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:

Crea un task, quindi effettuane il polling finché non termina.
  1. Richiesta: POST/image-to-3d

  2. Risposta: 202{ "result": "<task_id>" }task creato

  3. Ripeti ogni pochi secondi
    1. Richiesta: GET/image-to-3d/<task_id>

    2. Risposta: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5

  4. Richiesta: GET/image-to-3d/<task_id>

  5. Risposta: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }

Se la tua app smette di attendere, il task continua a essere eseguito. Effettua una 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.

Generazione 3D

APIConfigurazionemeshy-7.1 (latest)meshy-6meshy-6-litemeshy-t2
Testo in 3D (Preview)Solo mesh75 s90 s45 s10 s
Immagine in 3DSolo mesh75 s90 s40 s4 s
Mesh con texture 2K2 min3 min75 s60 s
Mesh con texture 4K2,5 min3,5 minNon supportato80 s
Mesh con texture 8K3,5 min4 minNon supportato2,5 min
Multi-immagine in 3DSolo mesh65 s2 min30 sNon supportato
Mesh con texture 2K2,5 min3,5 min85 sNon supportato
Mesh con texture 4K3 min4 minNon supportatoNon supportato
Mesh con texture 8K3,5 min4,5 minNon supportatoNon 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

APIRisoluzione textureTempo tipico
Testo in 3D (Refine)2K o 4K80 s
8K3,5 min
Retexture2K55 s
4K90 s
8K2,5 min

Generazione immagini

APInano-banananano-banana-2nano-banana-proModelli GPT Image
Testo in immagine20 s15 s25 sda 20 a 35 s
Immagine in immagine40 s20 s30 sda 20 a 40 s

Rigging e Animazione

APIConfigurazioneTempo tipico
Auto-RiggingRigging automatico40 s
AnimazionePer richiesta15 s
Testo in movimentomode prime15 s
mode swift10 s

Post-elaborazione

APITempo tipico
Remesh2 min
Unwrap UV35 s
Converti7 s
Ridimensiona15 s

Stampa 3D

APIConfigurazioneTempo tipico
Analizza stampabilitàSolo controlli della mesh1 s
Controlli della mesh e delle pareti sottili10 s
Multi-ColorPer richiesta30 s
Ripara stampabilitàSolo riparazione della mesh10 s
Controllo pareti sottili, pareti mantenute20 s
Controllo pareti sottili, pareti ispessite100 s
Auto SplitParti a colore uniforme70 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_at del 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 FAILED significa che il task è fallito. Meshy rimborsa automaticamente i task falliti.

Usa questi valori nel tuo codice:

ImpostazioneValore consigliato
Timeout della richiesta di creazione (POST)60 secondi
Timeout della richiesta di creazione (POST) con un file model_url oltre 100 MB120 secondi. Meshy scarica il file prima di rispondere.
Timeout della richiesta di stato (GET)30 secondi
Intervallo di pollingL'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 taskAlmeno 60 minuti dal created_at. Non riavviare questo conteggio quando riconnetti uno stream.
StreamUno 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.