Avvio rapido
Inizia creando la tua chiave API
Ogni richiesta in questa guida ne ha bisogno. Creare una chiave richiede pochi secondi.
Crea la tua chiave APICrea il tuo primo modello 3D con la REST API di Meshy in quattro passaggi, dalla creazione di una chiave API al download del modello.
Usi un assistente di codifica AI? Per collegare Claude Code, Cursor, Windsurf o un altro client MCP a Meshy, consulta Integrazione AI. Per un agente di chat senza supporto MCP, usa llms.txt.
1Ottieni la tua chiave API
Crea una chiave API nella pagina API Keys della Developer Platform. Non potrai più visualizzare la chiave dopo aver lasciato quella schermata, quindi conservala in un luogo sicuro. Inviala in ogni richiesta come token Bearer nell'header Authorization. Consulta Autenticazione.
È necessario un piano a pagamento per creare e gestire le chiavi API. Con il piano Free non puoi creare chiavi personali, e il Playground usa una chiave integrata per i test.

Tieni la chiave lontana dai tuoi script. Conservala invece in una variabile d'ambiente, come mostrato nel passaggio successivo.
2Crea un'attività Immagine in 3D
Invia un'immagine a Immagine in 3D. Per partire invece da un prompt di testo o da più foto, usa Testo in 3D o Multi-immagine in 3D.
Prima, memorizza la tua chiave in una variabile d'ambiente:
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.
I seguenti esempi usano tutti questa foto. Per provare un'altra immagine, modifica image_url.

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 dell'attività
L'attività viene eseguita in background e di solito richiede alcuni minuti. Recupera l'attività dallo stesso endpoint finché status non è SUCCEEDED, FAILED o CANCELED. Nella seguente richiesta, sostituisci <task_id> con l'ID restituito dal passaggio 2. Tra una richiesta e l'altra, attendi il numero di secondi indicato nell'header Retry-After.
Per i tempi di elaborazione tipici, e per quanto tempo attendere prima di arrendersi, consulta Ciclo di vita dell'attività.
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": null
}
Se l'attività fallisce, status è FAILED, e task_error indica il motivo. Correggi l'input o crea un'altra attività. Consulta Errori.
Per ricevere una notifica al termine dell'attività invece di effettuare il polling, effettua lo streaming dell'attività oppure usa un webhook.
4Scarica il tuo modello
I file si trovano in model_urls nella risposta precedente. Ogni formato (GLB, FBX, OBJ, USDZ e STL) ha un URL firmato valido per un tempo limitato. Puoi anche incollare l'URL nel tuo browser per scaricare il file.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

Su tutti i piani tranne Enterprise, Meshy conserva i file per 3 giorni. Scarica i file di cui hai bisogno entro quel termine. Consulta Conservazione degli asset.
Mettiamo tutto insieme
Questo script crea l'attività, attende il suo completamento e scarica il modello.
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 lo scheletro a una mesh umanoide in modo che sia pronta per l'animazione in Unity o Unreal.
Learn more →Mesh Smart Topology
Imposta model_type su smart-topology in Immagine in 3D per ottenere una mesh triangolare pulita e pronta per il gioco.
Modello per stampa 3D
Converti un modello finito in un file 3MF multicolore, pronto per lo slicing e la stampa.
Learn more →Prossimi passi
- Esplora ogni endpoint nel riferimento API.
- Prima di passare alla produzione, consulta Prezzi, Limiti di frequenza ed Errori.
- Segui le ricette passo-passo nel Cookbook.