lowpoly wird am 30.10.2026 abgeschaltet. meshy-7 wird als 3D-Generierungsmodell am 31.12.2026 abgeschaltet; als Texturmodell bleibt es verfügbar. Wechseln Sie vor diesen Terminen das Modell, um Fehler bei Anfragen zu vermeiden. Alle Abkündigungen ansehen

Schnellstart

Beginnen Sie mit der Erstellung Ihres API-Schlüssels

Jede Anfrage in diesem Leitfaden benötigt einen. Das Erstellen eines Schlüssels dauert nur wenige Sekunden.

API-Schlüssel erstellen

Erstellen Sie Ihr erstes 3D-Modell mit der Meshy REST API in vier Schritten – von der Erstellung eines API-Schlüssels bis zum Herunterladen des Modells.


1Holen Sie sich Ihren API-Schlüssel

Erstellen Sie einen API-Schlüssel auf der Seite API Keys der Developer Platform. Sie können den Schlüssel nach Verlassen dieses Bildschirms nicht erneut einsehen, bewahren Sie ihn daher an einem sicheren Ort auf. Senden Sie ihn bei jeder Anfrage als Bearer-Token im Authorization-Header. Siehe Authentifizierung.

Sie benötigen einen kostenpflichtigen Plan, um API-Schlüssel zu erstellen und zu verwalten. Im Free-Plan können Sie keine eigenen Schlüssel erstellen, und der Playground verwendet einen integrierten Schlüssel zum Testen.

Öffnen Sie die Seite „API Keys“ in der Developer Platform und erstellen Sie dann Ihren Schlüssel


2Eine Bild-zu-3D-Aufgabe erstellen

Senden Sie ein Bild an Bild zu 3D. Um stattdessen mit einem Text-prompt oder mehreren Fotos zu starten, verwenden Sie Text zu 3D oder Multi-Bild zu 3D.

Speichern Sie zunächst Ihren Schlüssel in einer Umgebungsvariablen:

Export your key

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

Die folgenden Beispiele verwenden alle dieses Foto. Um ein anderes Bild auszuprobieren, ändern Sie image_url.

Beispielhafte Fantasy-Charakter-Illustration, die in diesem Leitfaden als Bild-zu-3D-Eingabe verwendet wird
Beispieleingabe

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

3Aufgabenstatus prüfen

Die Aufgabe läuft im Hintergrund und dauert in der Regel einige Minuten. Rufen Sie die Aufgabe vom selben Endpunkt ab, bis status den Wert SUCCEEDED, FAILED oder CANCELED hat. Ersetzen Sie in der folgenden Anfrage <task_id> durch die ID, die Schritt 2 zurückgegeben hat. Warten Sie zwischen den Anfragen die Anzahl der Sekunden, die im Retry-After-Header angegeben ist.

Informationen zu typischen Bearbeitungszeiten und wie lange Sie warten sollten, bevor Sie abbrechen, finden Sie unter 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": null
}

Wenn die Aufgabe fehlschlägt, hat status den Wert FAILED, und task_error nennt den Grund. Korrigieren Sie die Eingabe oder erstellen Sie eine neue Aufgabe. Siehe Fehler.


4Ihr Modell herunterladen

Die Dateien befinden sich unter model_urls der vorherigen Antwort. Jedes Format (GLB, FBX, OBJ, USDZ und STL) besitzt eine signierte URL, die für eine begrenzte Zeit gültig ist. Sie können die URL auch in Ihren Browser einfügen, um die Datei herunterzuladen.

Download

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
Das resultierende 3D-Modell, das aus dem Beispiel-Fantasy-Charakterfoto generiert wurde
Ihr Ergebnis

Alles zusammenfügen

Dieses Skript erstellt die Aufgabe, wartet auf deren Abschluss und lädt das Modell herunter.

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

Häufige Workflows erkunden


Nächste Schritte