API Testo in 3D

Questo campo deve essere impostato su "preview" quando si crea un task di preview.

Descrive il tipo di oggetto che rappresenta il modello 3D. Massimo 800 caratteri.

Specifica il tipo di generazione della mesh 3D.

Valori disponibili:

• standard: Generazione di mesh 3D standard ad alto dettaglio.
• smart-topology: Scegli il modello Smart Topology con ai_model (meshy-t2).
• lowpoly (deprecato, verrà ritirato il 30 ottobre 2026): Genera una mesh low-poly ottimizzata per poligoni più puliti. Consigliamo di usare invece Meshy T2: smart-topology con meshy-t2.

ID del modello da utilizzare. I valori disponibili dipendono da model_type.

Generazione standard (model_type: standard):

• meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
• meshy-7 (deprecato): usa invece meshy-7.1.

Generazione Smart Topology (model_type: smart-topology):

• meshy-t2 (predefinito): il modello Smart Topology — topology più pulita, parti separate in modo nativo, output triangolare e un numero di facce impostabile con target_polycount.

Passaggio di generazione della geometria. 2k esegue il passaggio Ultra a 2048³; 4k lo esegue a 4096³ per il massimo dettaglio superficiale.

Valori disponibili: standard, 2k, 4k

Usa invece geometry_resolution. ultra_mode: true equivale a geometry_resolution: "2k".

Controlla se abilitare la fase di remesh. Per il modello con la qualità più alta, consigliamo di impostare should_remesh su false.

Numero di poligoni (facce) desiderato nell'output. Il conteggio effettivo può discostarsi dal target a seconda della geometria.

target_polycount ha effetto in due casi indipendenti:

• Remesh — con should_remesh: true su un modello standard. La mesh viene sottoposta a remesh (decimata) fino a raggiungere approssimativamente questo conteggio. Intervallo da 100 a 300.000, predefinito 30.000. Se decimation_mode è impostato, ha la priorità e target_polycount viene ignorato.
• Smart Topology — con model_type: smart-topology e ai_model: meshy-t2. Il modello viene generato direttamente con questo numero di facce; non viene eseguito alcun remesh e should_remesh non è richiesto. Intervallo da 100 a 15.000, predefinito 4.000.

Deprecato. Questo parametro non influisce più sull'output.

Il campo symmetry_mode controlla il comportamento della simmetria durante il processo di generazione del modello.

I valori validi sono:

• off: Disabilita la simmetria.
• auto: Determina e applica automaticamente la simmetria in base alla geometria di input.
• on: Impone la simmetria durante la generazione.

Specifica il pose_mode per il modello generato.

Valori disponibili:

• a-pose: Genera il modello in posa A.
• t-pose: Genera il modello in posa T.
• "" (stringa vuota): Nessuna posa specifica applicata.

Usa invece pose_mode. Indica se generare il modello in posa A/T.

Non supportato da Meshy-6. Le richieste che usano Meshy-6 ignoreranno art_style, e alcune combinazioni potrebbero causare errori. Valori disponibili: realistic, sculpture.

Quando impostato su true, il contenuto in input verrà automaticamente analizzato per individuare eventuali contenuti potenzialmente dannosi. Se viene rilevato contenuto dannoso, il task non proseguirà con la generazione.

Il testo di prompt verrà analizzato.

Specifica quali formati di file 3D includere nell'output. Verranno generati e restituiti solo i formati richiesti, il che può ridurre i tempi di completamento del task. Se omesso, vengono inclusi tutti i formati supportati.

Valori disponibili: glb, obj, fbx, stl, usdz, 3mf

Quando impostato su true, il task genera inoltre una versione con sfondo trasparente (RGBA) della preview e la restituisce come alpha_thumbnail_url nella risposta GET. Il campo esistente thumbnail_url rimane invariato.

Quando impostato su true, il servizio utilizza la visione artificiale per stimare automaticamente l'altezza reale dell'oggetto e ridimensionare di conseguenza il modello. L'origine sarà impostata su bottom per impostazione predefinita, a meno che origin_at non venga impostato esplicitamente.

La richiesta non è stata accettata. Cause comuni:

• Parametro mancante: Manca un parametro obbligatorio (ad es. prompt, mode).
• Parametro non valido: art_style non è uno dei valori consentiti.
• Prompt troppo lungo: Il prompt supera il limite di caratteri.
• Modello non supportato per low poly: ai_model: "meshy-6-lite" non supporta model_type: "lowpoly".
• Modello non supportato per Ultra: geometry_resolution richiede meshy-7.1 o latest.

Autenticazione non riuscita. Controlla la tua chiave API.

Crediti insufficienti per eseguire questo task.

Hai superato il tuo limite di frequenza.

Questo campo deve essere impostato su "refine" quando si crea un'attività refine.

L'id dell'attività di preview corrispondente.

Lo stato dell'attività di preview specificata deve essere SUCCEEDED.

Genera mappe PBR (metallic, roughness, normal) oltre al base color. Una mappa di emissione viene inclusa anche quando ai_model è meshy-6, eccetto con texture_resolution: 8k (in quel caso non viene prodotta alcuna mappa di emissione). meshy-6-lite, meshy-7.1 e latest non producono una mappa di emissione.

Risoluzione della texture del base color. Uno tra 2k (2048×2048), 4k (4096×4096) o 8k (8192×8192). Risoluzioni più alte catturano maggiori dettagli superficiali. Si applica solo al mode refine.

Usa texture_resolution al suo posto — equivale a texture_resolution: "4k". Quando entrambi sono impostati, texture_resolution ha la precedenza.

Fornisce un prompt testuale aggiuntivo per guidare il processo di texturing. Massimo 800 caratteri.

Fornisce un'immagine 2d per guidare il processo di texturing. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.

Dimensione massima del file: 20 MB.

Ci sono due modi per fornire l'immagine:

• URL pubblicamente accessibile: un URL raggiungibile dalla rete internet pubblica
• Data URI: un data URI dell'immagine codificato in base64. Esempio di data URI: data:image/jpeg;base64,<i tuoi dati immagine codificati in base64>

ID del modello da usare per il refine.

Valori disponibili:

• meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
• meshy-7 (deprecato): usa meshy-7.1 al suo posto.

Ometti questo parametro per ereditare il modello usato dall'attività di preview, in modo che una preview e il suo refine restino sullo stesso modello end to end. Fornisci un valore esplicito per sovrascrivere questa ereditarietà.

Quando impostato su true, il contenuto in input verrà automaticamente analizzato alla ricerca di contenuti potenzialmente dannosi. Se viene rilevato contenuto dannoso, l'attività non procederà alla generazione.

Verranno analizzati sia il testo di texture_prompt sia l'immagine di texture_image_url.

Rimuove luci e ombre dalla texture del base color, producendo un risultato più pulito che funziona meglio con configurazioni di illuminazione personalizzate.

Specifica quali formati di file 3D includere nell'output. Verranno generati e restituiti solo i formati richiesti, il che può ridurre i tempi di completamento dell'attività. Se omesso, vengono inclusi tutti i formati supportati.

Valori disponibili: glb, obj, fbx, stl, usdz, 3mf

Quando impostato su true, l'attività genera inoltre una versione con sfondo trasparente (RGBA) della preview e la restituisce come alpha_thumbnail_url nella risposta GET. Il campo thumbnail_url esistente rimane invariato.

Quando impostato su true, il servizio usa la visione AI per stimare automaticamente l'altezza reale dell'oggetto e ridimensionare il modello di conseguenza. L'origine sarà impostata su bottom per impostazione predefinita, a meno che origin_at non venga impostato esplicitamente.

La richiesta non è stata accettata. Cause comuni:

• ID attività non valido: il preview_task_id non è valido o non esiste.
• Attività non pronta: l'attività di preview non è ancora terminata con successo.
• Incompatibilità di modello: il modello AI dell'attività di preview non è compatibile con il modello di refine richiesto.

Autenticazione fallita. Controlla la tua chiave API.

Crediti insufficienti per eseguire questa attività.

L'attività di preview specificata da preview_task_id non è stata trovata.

Hai superato il limite di frequenza.

Identificatore univoco dell'attività Testo in 3D da recuperare.

L'ID del task Testo in 3D da eliminare.

Numero di pagina per la paginazione.

Limite dimensione pagina. Il massimo consentito è 100 elementi.

Campo per cui ordinare.

Valori disponibili:

• +created_at: Ordina per data di creazione in ordine crescente.
• -created_at: Ordina per data di creazione in ordine decrescente.

Identificativo univoco del task Testo in 3D da trasmettere in streaming.

Identificatore univoco del task. Anche se utilizziamo un UUID k-sortable per gli id dei task come dettaglio implementativo, non dovresti fare nessuna ipotesi sul formato dell'id.

Tipo del task Testo in 3D. I valori possibili sono text-to-3d-preview per i task della fase preview e text-to-3d-refine per i task della fase refine.

URL scaricabile del file del modello 3D con texture generato da Meshy. La proprietà per un formato verrà omessa se il formato non viene generato, invece di restituire una stringa vuota.

Questo è il prompt non modificato che è stato utilizzato per creare il task.

Mantenuto per retrocompatibilità. Questo campo non ha alcun impatto funzionale sui modelli generati.

L'art_style non modificato che è stato utilizzato per creare il task di preview. Non supportato da Meshy-6.

Mantenuto per retrocompatibilità. Questo campo non ha alcun impatto funzionale sui modelli generati.

Prompt testuale aggiuntivo fornito per guidare il processo di texturing durante la fase refine.

Deprecato; leggi invece geometry_resolution.

Il livello Ultra con cui è stato eseguito il task di preview (2k o 4k); omesso per standard.

URL scaricabile dell'immagine texture che è stata utilizzata per guidare il processo di texturing.

URL scaricabile dell'immagine miniatura del file del modello.

URL scaricabile di una versione con sfondo trasparente (RGBA) di thumbnail_url. Presente solo quando il task è stato creato con alpha_thumbnail: true e l'anteprima trasparente è stata renderizzata con successo; in caso contrario questo campo viene omesso.

URL scaricabile del video di anteprima. Verrà rimosso in una futura release.

Progresso del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task è riuscito, diventerà 100.

Timestamp di quando il task è stato avviato, in millisecondi. Se il task non è ancora iniziato, questa proprietà sarà 0.

Timestamp di quando il task è stato creato, in millisecondi.

Timestamp di quando il task è stato completato, in millisecondi. Se il task non è ancora terminato, questa proprietà sarà 0.

Stato del task. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Un array di oggetti URL di texture generati dal task. Normalmente contiene solo un oggetto URL di texture. Ogni URL di texture ha le seguenti proprietà:

Il numero di task precedenti.

Dettagli dell'errore per i task non riusciti. Consulta Errori per il riferimento completo all'oggetto task_error.

Il numero di crediti consumati da questo task. Presente quando lo stato del task è PENDING, IN_PROGRESS o SUCCEEDED. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di fallimento).