lowpoly verrà ritirato il 30 ott 2026. meshy-7 come modello di generazione 3D verrà ritirato il 31 dic 2026; come modello di texture resta disponibile. 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 ha bisogno. Creare una chiave richiede pochi secondi.

Crea la tua chiave API

Crea il tuo primo modello 3D con la REST API 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 le chiavi API. Con il piano Free non puoi creare chiavi personali, e il Playground usa 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 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>"

I seguenti esempi usano 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 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

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

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


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

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


Prossimi passi