Guida all'uso di Image to 3D Model API: Manuale completo 2026

L'API Image to 3D Model trasforma una singola foto in un modello 3D pronto per la produzione in pochi secondi—senza bisogno di modellazione manuale. Modellare a mano ogni asset è lento e costoso, e per studi di giochi, app AR e team di e-commerce diventa rapidamente il collo di bottiglia che ritarda i lanci. L'API image-to-3D di Meshy rimuove questo attrito: invia un'immagine, convertila in un modello 3D in secondi e scarica una mesh completamente texturizzata in formati come GLB, FBX e OBJ. Questa guida ti accompagna attraverso l'intero flusso di lavoro—dalla creazione della tua chiave API al download del tuo primo modello—con codice copia-e-incolla che puoi eseguire in pochi minuti.

Cos'è l'API Image to 3D Model?

In sostanza, l'API Image to 3D Model è un endpoint REST basato sull'AI image to 3D model di Meshy. Invi una singola immagine (JPG, JPEG o PNG) come URL pubblico o stringa base64, e l'API restituisce un modello 3D texturizzato—geometria e texture del colore base incluse—in formati standard come GLB, FBX, OBJ, USDZ, STL e 3MF. I componenti aggiuntivi opzionali includono mappe PBR, texture fino a 4K e miniature di anteprima multi-angolo.

Basata sul nostro ultimo modello Meshy 6, l'API ti permette di configurare topologia e conteggio dei poligoni, impostare modalità di posa e guidare la texturizzazione con un prompt testuale o un'immagine di riferimento—ideale per generare asset per giochi, AR/VR, stampa 3D e visualizzazione di prodotti.

Cosa ti serve per usare l'API Image to 3D?

Non ti serve molto per seguire questa guida. Assicurati di avere:

• Un account Meshy — registrati gratuitamente se non ne hai uno. Genererai la tua chiave API dalla dashboard nel Passo 1.

• Una chiave API — usata per autenticare ogni richiesta. Ti guideremo nella creazione di una, e puoi usare la chiave in modalità test gratuita per seguire senza consumare crediti.

• Un'immagine di input — un .jpg, .jpeg o .png chiaro ospitato a un URL pubblicamente accessibile (o codificato come base64). Uno sfondo pulito e un soggetto chiaramente visibile danno i migliori risultati.

• Un modo per fare richieste HTTP — curl (usato negli esempi seguenti), Postman o qualsiasi libreria HTTP nel tuo linguaggio preferito. Una familiarità di base con le API REST e JSON è utile ma non richiesta.

Questo è tutto—nessuna esperienza di modellazione 3D necessaria. Iniziamo.

Come Convertire un'Immagine in un Modello 3D con l'API (Guida Passo-Passo)

Passo 1: Configura le Tue Impostazioni API

Tutto ciò che ti serve per iniziare a costruire si trova nella pagina delle impostazioni API. Questo è il tuo centro di controllo per l'API Meshy, e ha tre sezioni chiave:

• Chiavi API — genera e gestisci le chiavi che autenticano le tue richieste.

• Webhook — ricevi notifiche automaticamente quando i tuoi task terminano.

• Utilizzo — monitora il tuo saldo crediti rimanente e il consumo API in tempo reale.

Esaminiamo ciascuna.

Ottieni la Tua Chiave API

Prima di fare qualsiasi richiesta, hai bisogno di una chiave API per autenticarti in modo sicuro. Nella pagina delle impostazioni API, clicca su Genera Chiave API. Ogni chiave segue il formato msy-<stringa-casuale>.

Suggerimento: Una volta generata, conserva la tua chiave API in un luogo sicuro (es. un gestore di password o una variabile d'ambiente). Trattala come una password—non impegnarla mai nel controllo del codice sorgente o esporla in codice lato client.

Chiave API in Modalità Test

Durante lo sviluppo e il test, puoi usare la chiave API in modalità test per esplorare l'API senza consumare i tuoi crediti:

msy_dummy_api_key_for_test_mode_12345678

Questa chiave speciale ha le seguenti caratteristiche:

• Può essere usata per fare richieste a tutti gli endpoint API Meshy.

• Nessun credito viene consumato usando questa chiave.

• Tutte le richieste valide restituiscono lo stesso risultato del task di esempio, indipendentemente dai parametri di input.

• La struttura dei dati di risposta corrisponde esattamente all'API di produzione.

Questo la rende perfetta per testare la tua integrazione prima di passare alla tua vera chiave API.

Configura Webhook (Opzionale)

Generare un modello 3D richiede tempo, quindi invece di interrogare ripetutamente l'API per verificare se un task è completato, puoi lasciare che Meshy ti notifichi nel momento in cui finisce. Ecco a cosa servono i webhook.

Nella sezione Webhook della pagina delle impostazioni, aggiungi un URL endpoint dove Meshy dovrebbe inviare le notifiche degli eventi. Quando un task cambia stato (ad esempio, quando viene completato o fallisce), Meshy invia una richiesta HTTP POST al tuo URL con i dettagli del task nel payload.

Suggerimento: I webhook sono l'approccio consigliato per la produzione. Riducano le chiamate API non necessarie e permettono alla tua applicazione di reagire ai risultati in tempo reale. Per test rapidi, il polling funziona comunque bene. Per testare il codice webhook localmente, puntalo a un URL proxy da un servizio come smee.io.

Prova Senza Codice — API Playground (Opzionale)

Hai già la tua Chiave API? Prima di scrivere codice, puoi eseguire un vero task Image to 3D direttamente nel tuo browser.

Apri meshy.ai/api-playground, seleziona Image to 3D dal pannello di sinistra e inserisci tre cose:

1. Autorizzazione — incolla la tua Chiave API (msy-xxxxxxxxxx)

2. Immagine — carica un .jpg, .jpeg o .png dal tuo computer

3. Premi Invia

Il Playground invia il task e interroga i risultati automaticamente. Una volta completato, vedrai l'anteprima del modello 3D e i link per il download direttamente nel browser — nessun codice richiesto.

Consiglio da professionista: Il pannello della richiesta/risposta grezza a destra mostra esattamente cosa l'API invia e restituisce. Puoi copiare il contenuto direttamente — prendi il task_id dalla risposta e i model_urls una volta che il task finisce. Li userai entrambi nei prossimi passaggi.

Passo 2: Invia un Task Image to 3D

Con la tua chiave API pronta, avvia un task con una singola richiesta POST:

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

Riceverai una risposta come questa:

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Il valore result è il tuo task_id — salvalo. Ti servirà nel prossimo passaggio per controllare l'avanzamento e recuperare il tuo modello.

Opzionale: Per ricevere una notifica automatica quando il task finisce, aggiungi un campo webhook_url al corpo JSON—ad esempio "webhook_url": "https://yourapp.com/webhooks/meshy". Vedi il Passo 3, Opzione B per come funziona.

Passo 3: Ottieni i Tuoi Risultati

Il tuo task non finisce istantaneamente—Meshy lo elabora in background. Hai due modi per ottenere il risultato:

Opzione A: Interroga per lo Stato (Il Più Semplice)

Invia una richiesta GET ogni 5 secondi finché status non cambia in SUCCEEDED:

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

La risposta appare così:

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

Alcuni campi degni di nota:

• model_urls contiene un link per il download per ogni formato generato. Per impostazione predefinita include glb, fbx, obj, usdz, stl e mtl (il file materiale che si abbina a obj).

• model_url è una scorciatoia al link GLB—utile quando ti serve solo GLB.

• consumed_credits mostra quanti crediti ha usato il task (è 0 per i task falliti, poiché i crediti vengono rimborsati).

• thumbnail_url è sempre presente e punta alla miniatura della vista frontale.

• thumbnail_urls appare solo quando multi_view_thumbnails: true, e contiene le viste frontale, destra, posteriore e sinistra.

• alpha_thumbnail_url appare solo quando alpha_thumbnail: true, e contiene la miniatura con sfondo trasparente.

Possibili valori di status: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Opzione B: Webhook (Consigliato per la Produzione)

Se hai impostato un webhook_url nel Passo 2, Meshy invierà l'oggetto del task completato al tuo URL automaticamente—nessun polling necessario.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 Quale dovrei usare? Il polling va bene per prototipi e task singoli. Usa i webhook in produzione — è più affidabile e risparmia chiamate API.

Passo 4: Scarica il Tuo Modello 3D

Una volta che status è SUCCEEDED, prendi gli URL di download da model_urls e scarica il formato che ti serve:

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

Il flag -o model.glb salva il file nella tua directory di lavoro corrente con quel nome—usa un percorso completo (es. -o /path/to/model.glb) per salvarlo altrove.

Per impostazione predefinita, ogni task restituisce GLB, FBX, OBJ, USDZ, STL e MTL (il file materiale per OBJ). 3MF è opzionale—lo ottieni solo quando lo richiedi esplicitamente tramite target_formats (vedi la tabella dei parametri sotto).

⚠️ I link scadono in 3 giorni (i piani Enterprise ottengono link permanenti). Scarica e conserva i tuoi modelli tempestivamente — i link non funzioneranno dopo la scadenza e dovrai rieseguire il task.

Pronto a usare questo modello nel tuo strumento DCC? Vedi la guida Bridge to Blender—Meshy ha anche bridge per Unity, Unreal, Maya e altri.

Come ottenere i migliori risultati image-to-3D?

• Usa un singolo soggetto chiaramente visibile. Un oggetto principale, centrato e completamente nell'inquadratura, fornisce all'AI il riferimento più pulito—evita scene affollate, ritagli pesanti e angoli estremi.

• Preferisci uno sfondo pulito e ordinato. Sfondi solidi o semplici aiutano il modello a separare il soggetto dall'ambiente circostante.

• Usa un'illuminazione uniforme e diffusa. Ombre dure e forti riflessi possono incorporare dettagli fuorvianti nella texture generata.

• Inizia con un'immagine ad alta risoluzione e nitida. Più dettagli in ingresso equivalgono a più dettagli in uscita—input sfocati o a bassa risoluzione producono modelli più morbidi.

Quali linguaggi di programmazione posso usare con l'API Image to 3D?

Qualsiasi linguaggio che possa fare richieste HTTP—invi un POST con JSON e interroghi con GET. Opzioni comuni:

• Python — usa la libreria requests o httpx

• JavaScript / TypeScript — usa fetch (integrato) o axios

• Go — usa net/http dalla libreria standard

• cURL — ottimo per test rapidi dal terminale

Puoi anche trovare esempi di codice pronti da copiare per tutti e quattro nell'API Playground.

Quanti crediti costa un task Image to 3D?

Il costo dipende dalla versione del modello e dal fatto che tu generi texture. La configurazione predefinita (meshy-6 con texturizzazione) costa 30 crediti per task:

I task falliti vengono rimborsati automaticamente—consumed_credits restituisce 0. Controlla sempre Prezzi per le tariffe più recenti.

Quali parametri accetta l'API Image to 3D?

Invia un POST a /openapi/v1/image-to-3d con questi parametri: Richiesto (uno tra):

Opzionale:

Prossimi passi con l'API Image to 3D

Ora hai il flusso di lavoro completo: crea una chiave API, invia un'immagine, interroga o usa un webhook per il risultato, poi scarica il tuo modello. Gli stessi quattro passaggi scalano da un prototipo rapido a una pipeline di produzione che trasforma migliaia di immagini in asset 3D automaticamente. Prendi la tua chiave dalla pagina delle impostazioni API e spedisci il tuo primo modello oggi. Preferisci iniziare da un prompt invece che da una foto? Usa l'API Text to 3D Model.

Domande Frequenti

Come converto un'immagine in un modello 3D tramite l'API?

Invia una richiesta POST a /openapi/v1/image-to-3d con il tuo image_url e la chiave API, poi interroga il task (o usa un webhook) finché il suo status non è SUCCEEDED. La risposta restituisce i link per il download del modello generato. Il flusso completo in quattro passaggi—chiave, invio, recupero, download—è coperto nella guida passo-passo sopra.

Quali formati di output (STL, GLB, OBJ) supporta l'API?

Ogni task restituisce GLB, FBX, OBJ, USDZ, STL e MTL per impostazione predefinita, con 3MF disponibile su richiesta tramite target_formats. GLB è il migliore per il web e AR, FBX e OBJ per strumenti DCC e motori di gioco, USDZ per AR su iOS e STL per la stampa 3D.

Quali formati immagine posso caricare?

L'API Image to 3D supporta immagini JPG, JPEG e PNG fino a 100 MB—più grandi del limite di 20 MB nell'interfaccia del Workspace Meshy. Per i risultati più accurati, usa un PNG con sfondo trasparente o bianco pulito, che aiuta l'API a isolare il soggetto e generare un modello 3D di qualità superiore.

Posso ottenere un modello 3D texturizzato dall'API?

Sì. La texturizzazione è abilitata per impostazione predefinita ("should_texture": true). Per aggiungere mappe PBR (metallico, ruvidità, normale), imposta "enable_pbr": true—su meshy-6/latest questo include anche una mappa di emissione. Per una texture del colore base a 4K, imposta "hd_texture": true (supportato solo su meshy-6/latest; le mappe PBR rimangono a 2K). Puoi anche guidare lo stile della texture con un texture_prompt o un texture_image_url.

Posso generare un modello 3D pronto per la stampa 3D (STL)?

Sì—STL è generato per impostazione predefinita, quindi una conversione da immagine a STL 3D non necessita di parametri extra: basta prendere model_urls.stl quando il task viene completato. Questo rende semplici i flussi di lavoro da immagine a stampa 3D, poiché STL è il formato standard che gli slicer si aspettano. Se vuoi solo STL, imposta "target_formats": ["stl"] per saltare gli altri formati e ridurre il tempo di generazione.

Quali piani includono l'accesso API?

L'accesso API è disponibile sui piani Pro, Studio ed Enterprise—è una funzionalità da Pro in su. Il piano gratuito Starter non include l'accesso API. Vedi Prezzi per i dettagli.

Quanto sono validi i link per il download?

I link per il download sono validi per 3 giorni sui piani Pro e Studio. I clienti Enterprise ottengono link permanenti. Salva i tuoi file tempestivamente—i link scaduti non possono essere recuperati e dovrai rieseguire il task.

Posso eseguire più task contemporaneamente?

Sì, le richieste concorrenti sono supportate. Se ricevi un errore 429 Too Many Requests, il tuo account ha raggiunto il limite di frequenza—implementa backoff esponenziale e riprova. Vedi la pagina Limiti di Frequenza per i limiti del tuo piano.

Il task mostra FAILED — cosa faccio?

Controlla task_error.message per la causa. Errori comuni:

Se il problema persiste, contatta il supporto Meshy.