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 API

Quattro passaggi per ottenere il tuo primo modello 3D, usando la REST API di Meshy.


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.

Apri la pagina API Keys nella Developer Platform, quindi crea la tua chiave


2Effettua la tua prima richiesta Immagine in 3D

Esporta la tua chiave, quindi crea il tuo primo task con Immagine in 3D. Preferisci lavorare a partire da un prompt testuale o da più foto? Consulta Testo in 3D o Multi-immagine in 3D.

Export your key

export MESHY_API_KEY="<your-api-key>"

Ogni esempio qui sotto usa questa foto — sostituisci il tuo image_url per provare qualcos'altro.

Sample fantasy character illustration used as the Image to 3D input in this guide
Sample input

Request

POST
/openapi/v1/image-to-3d
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

Le richieste restituiscono immediatamente un ID di task. Interroga lo stesso endpoint finché status non è SUCCEEDED — sostituisci <task_id> qui sotto con l'ID restituito nel passaggio 2.

Request

GET
/openapi/v1/image-to-3d/:id
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": ""
  }
}

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

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
The resulting 3D model generated from the sample fantasy character photo
Your result

Mettere tutto insieme

Preferisci un unico script che faccia tutto: crea, interroga, scarica?

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 },
);
const taskId = created.result;

// 2. Poll until it finishes
let task;
while (true) {
  const { data } = await axios.get(`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`, { headers });
  task = data;
  if (task.status === 'SUCCEEDED' || task.status === 'FAILED') break;
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

// 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 più comuni


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 webhook.
  • Esplora la documentazione di riferimento API completa per ogni endpoint.
  • Controlla Prezzi, Limiti di frequenza ed Errori prima di passare alla produzione.
  • Consulta il changelog per aggiornamenti e correzioni di bug.
  • Hai feedback o riscontri problemi? Unisciti alla nostra community su Discord — ci farebbe piacere sentirti!