Avvio rapido

Inizia creando la tua chiave API

Ogni richiesta in questa guida ne ha bisogno. Creare una chiave richiede meno di un minuto.

Crea la tua chiave API

Quattro passaggi per il tuo primo modello 3D, utilizzando l'API REST di Meshy.


1Ottieni la tua chiave API

Crea una chiave API dalle impostazioni del tuo account — non potrai visualizzarla di nuovo dopo questa schermata, quindi conservala in un luogo sicuro. Ogni richiesta si autentica con un token Bearer nell'intestazione Authorization — vedi Autenticazione.

Apri Impostazioni API dal menu API, 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. Lavori da un prompt testuale o da più foto invece? Vedi Testo in 3D o Multi-immagine in 3D.

Esporta la tua chiave

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

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

Illustrazione di un personaggio fantasy di esempio utilizzata come input Immagine in 3D in questa guida
Input di esempio

Richiesta

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 task. Interroga lo stesso endpoint finché lo status non è SUCCEEDED — sostituisci <task_id> qui sotto con l'ID restituito nel passaggio 2.

Richiesta

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

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

Scarica il modello da model_urls nella risposta sopra. Ogni formato (GLB, FBX, OBJ, USDZ, STL) è un URL firmato e a tempo limitato — oppure salta la riga di comando e incolla l'URL direttamente 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

Metti tutto insieme

Preferisci uno script che faccia tutto — crea, interroga, scarica?

Script completo

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 flussi di lavoro comuni


Prossimi passi