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

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

Crea il tuo primo modello 3D con l'API REST di Meshy in quattro passaggi, dalla creazione di una chiave API al download del modello.


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.

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


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

I seguenti esempi utilizzano tutti questa foto. Per provare un'altra immagine, modifica image_url.

Illustrazione di un personaggio fantasy di esempio usata come input per Immagine in 3D in questa guida
Esempio di 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. 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

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

Se il task fallisce, status è FAILED e task_error indica il motivo. Correggi l'input o crea un altro task. Consulta Errori.


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

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

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


Prossimi passi