lowpoly verrà ritirato il 30 ott 2026. Cambia modello prima di queste date per evitare errori nelle richieste.

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 API

Quattro passaggi per ottenere il tuo primo modello 3D, utilizzando 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, poi crea la tua chiave


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>"

Ogni esempio qui sotto utilizza 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

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

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
Il modello 3D risultante generato dalla foto di esempio del personaggio fantasy
Il tuo risultato

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


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!