lowpoly avvecklas den 30 okt. 2026. Byt modell före dessa datum för att undvika fel i förfrågningar. Se alla utfasningar

Snabbstart

Börja med att skapa din API-nyckel

Varje förfrågan i den här guiden behöver en. Att skapa en nyckel tar några sekunder.

Skapa din API-nyckel

Skapa din första 3D-modell med Meshys REST API i fyra steg, från att skapa en API-nyckel till att ladda ner modellen.


1Skaffa din API-nyckel

Skapa en API-nyckel på sidan API Keys i Developer Platform. Du kan inte se nyckeln igen efter att du lämnat den skärmen, så spara den på ett säkert ställe. Skicka den i varje förfrågan som en Bearer-token i Authorization-headern. Se Autentisering.

Du behöver en betalplan för att skapa och hantera API-nycklar. I Free-planen kan du inte skapa egna nycklar, och Playground använder en inbyggd nyckel för testning.

Öppna sidan API Keys i Developer Platform och skapa sedan din nyckel


2Skapa en Bild till 3D-uppgift

Skicka en bild till Bild till 3D. Om du i stället vill starta från en textprompt eller flera foton, använd Text till 3D eller Flera bilder till 3D.

Lagra först din nyckel i en miljövariabel:

Export your key

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

Följande exempel använder alla det här fotot. För att prova en annan bild, ändra image_url.

Exempel på fantasykaraktärsillustration som används som Bild till 3D-indata i den här guiden
Exempel på indata

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

3Kontrollera uppgiftens status

Uppgiften körs i bakgrunden och tar vanligtvis några minuter. Hämta uppgiften från samma endpoint tills status är SUCCEEDED, FAILED eller CANCELED. I följande förfrågan, ersätt <task_id> med det ID som steg 2 returnerade. Mellan förfrågningar, vänta det antal sekunder som anges i Retry-After-headern.

För typiska behandlingstider, och hur länge du bör vänta innan du ger upp, se Uppgiftens livscykel.

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
}

Om uppgiften misslyckas är status FAILED, och task_error anger varför. Åtgärda indata eller skapa en ny uppgift. Se Fel.


4Ladda ner din modell

Filerna finns i model_urls i föregående svar. Varje format (GLB, FBX, OBJ, USDZ och STL) har en signerad URL som fungerar under en begränsad tid. Du kan också klistra in URL:en i din webbläsare för att ladda ner filen.

Download

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
Den resulterande 3D-modellen genererad från exempelfotot med fantasykaraktären
Ditt resultat

Sätt ihop allt

Det här skriptet skapar uppgiften, väntar tills den är klar och laddar ner modellen.

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');

Utforska vanliga arbetsflöden


Nästa steg