Avvio rapido
Inizia creando la tua chiave API
Ogni richiesta di questa guida ne richiede una. Creare una chiave richiede pochi secondi.
Crea la tua chiave APIQuattro passaggi per ottenere il tuo primo modello 3D, utilizzando la REST API di Meshy.
Stai usando un assistente di programmazione AI? Consulta la pagina Integrazione AI — installa il Meshy MCP server per l'accesso tool-calling da Claude Code, Cursor, Windsurf e altri strumenti compatibili con MCP, oppure indirizza un semplice agente di chat a llms.txt.
1Ottieni la tua chiave API
Crea una chiave API dalla pagina API Keys nella Developer Platform — non potrai più visualizzarla dopo questa schermata, quindi conservala in un luogo sicuro. Ogni richiesta si autentica con un token Bearer nell'header Authorization — vedi Autenticazione.
La creazione e la gestione delle chiavi API richiede un piano a pagamento. Gli account Free ottengono una chiave dedicata e integrata per i test nel Playground, ma non possono creare o gestire chiavi proprie.

Suggerimento di sicurezza: evita di incollare la tua chiave direttamente negli script — salvala invece come variabile d'ambiente: export MESHY_API_KEY="msy_...".
2Effettua la tua prima richiesta di Immagine in 3D
Esporta la tua chiave, quindi crea la tua prima attività con Image to 3D. Stai lavorando con un prompt testuale o più foto invece? Consulta Text to 3D o Multi-Image to 3D.
Export your key
export MESHY_API_KEY="<your-api-key>"
Esegui questo comando nel tuo terminale (Terminal su macOS, Prompt dei comandi o PowerShell su Windows) — non in un browser.
Ogni esempio qui sotto utilizza questa foto — sostituisci il tuo image_url per provare qualcos'altro.

Request
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${MESHY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://docs.meshy.ai/images/api/quick-start/source-photo.webp"
}'
3Controlla lo stato del task
Il task viene eseguito in background e di solito richiede alcuni minuti. Esegui il polling dello stesso endpoint finché status non diventa SUCCEEDED, FAILED o CANCELED, sostituendo <task_id> qui sotto con l'ID restituito nel passaggio 2. Per i tempi tipici e quanto attendere, consulta Task Lifecycle.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
-H "Authorization: Bearer ${MESHY_API_KEY}"
Response — SUCCEEDED
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "SUCCEEDED",
"progress": 100,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"task_error": {
"message": ""
}
}
Il polling non fa per te? Usa lo streaming SSE oppure un webhook per essere avvisato nel momento esatto in cui un task termina.
4Scarica il tuo modello
Recupera il modello da model_urls nella risposta sopra. Ogni formato (GLB, FBX, OBJ, USDZ, STL) è un URL firmato e a tempo limitato — oppure, senza usare la riga di comando, incolla direttamente l'URL nella barra degli indirizzi del tuo browser per scaricarlo.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

I file vengono conservati per 3 giorni nei piani non Enterprise — consulta Conservazione degli asset.
Mettiamo tutto insieme
Preferisci uno script unico che faccia tutto — creazione, polling, download?
Full script
import axios from 'axios';
import fs from 'fs';
const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.ai/images/api/quick-start/source-photo.webp';
// 1. Create the task
const { data: created } = await axios.post(
'https://api.meshy.ai/openapi/v1/image-to-3d',
{ image_url: imageUrl },
{ headers, timeout: 60_000 },
);
const taskId = created.result;
// 2. Poll until it finishes, for up to 60 minutes
const deadline = Date.now() + 60 * 60 * 1000;
let task;
while (true) {
const { data, headers: resHeaders } = await axios.get(
`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`,
{ headers, timeout: 30_000 },
);
task = data;
if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(task.status)) break;
if (Date.now() > deadline) {
// The task is still running. Check it again later with the same task ID instead of creating a new one.
throw new Error(`Task ${taskId} is still ${task.status}; check it again later`);
}
const waitSeconds = Number(resHeaders['retry-after']) || 5;
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}
// 3. Download the result (only if the task succeeded)
if (task.status !== 'SUCCEEDED') {
throw new Error(`Task ${task.status}: ${task.task_error?.message || 'unknown error'}`);
}
const { data: model } = await axios.get(task.model_urls.glb, { responseType: 'arraybuffer' });
fs.writeFileSync('model.glb', model);
console.log('Saved model.glb');
Esplora i flussi di lavoro comuni
Personaggio pronto per il gioco
Applica il rigging a una mesh umanoide con uno scheletro, in modo che sia pronta per l'animazione in Unity o Unreal.
Learn more →Asset lowpoly
Imposta model_type su smart-topology in Immagine in 3D per ottenere una mesh pulita e pronta per il gioco.
Modello per stampa 3D
Converti un modello finito in un file 3MF multicolore, pronto per essere sezionato e stampato.
Learn more →Prossimi passi
- Preferisci un'interfaccia grafica? Apri la Developer Platform — esegui richieste nel Playground, monitora l'utilizzo e i log delle richieste e gestisci i webhooks.
- Esplora la API reference completa per ogni endpoint.
- Impara dagli esempi pratici: segui le ricette passo passo nel Cookbook e leggi i tutorial e le storie di sviluppo sul Developer Blog.
- Consulta Prezzi, Rate Limits ed Errori prima di passare alla produzione.
- Tieni d'occhio il changelog per aggiornamenti e correzioni di bug.
- Hai un feedback o riscontri problemi? Unisciti alla nostra community Discord — ci farebbe piacere sentirti!