Avvio rapido
Inizia creando la tua chiave API
Ogni richiesta in questa guida ne richiede una. Creare una chiave richiede pochi secondi.
Crea la tua chiave APICrea il tuo primo modello 3D con l'API REST di Meshy in quattro passaggi, dalla creazione di una chiave API al download del modello.
Utilizzi un assistente di codifica AI? Per connettere 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 chiavi API. Con il piano Free non puoi creare chiavi personali, e il Playground utilizza una chiave integrata per i test.

Tieni la chiave fuori 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 testuale 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 utilizzano 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 del task
Il task viene eseguito in background e di solito richiede alcuni minuti. Richiedi il task dallo stesso endpoint finché status non è SUCCEEDED, FAILED o CANCELED. Nella richiesta seguente, 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 sapere quanto attendere prima di arrendersi, consulta Ciclo di vita del task.
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": ""
}
}
Se il task fallisce, status è FAILED e task_error indica il motivo. Correggi l'input o crea un altro task. Consulta Errori.
Per ricevere una notifica quando il task termina invece di eseguire il polling, effettua lo streaming del task 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) dispone di un URL firmato valido per un periodo di 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 questo termine. Consulta Conservazione degli asset.
Mettiamo tutto insieme
Questo script crea il task, attende che venga completato 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
Esegui il rigging di una mesh umanoide con uno scheletro 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 essere sezionato e stampato.
Learn more →Prossimi passi
- Esplora tutti gli endpoint nella documentazione delle API.
- Prima di passare alla produzione, consulta Prezzi, Limiti di frequenza ed Errori.
- Segui le guide passo passo nel Cookbook.