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 erstellenErstellen 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.
Verwenden Sie einen KI-Coding-Assistenten? Um Claude Code, Cursor, Windsurf oder einen anderen MCP-Client mit Meshy zu verbinden, siehe KI-Integration. Für einen Chat-Agenten ohne MCP-Unterstützung verwenden Sie llms.txt.
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.

Halten Sie den Schlüssel aus Ihren Skripten fern. Speichern Sie ihn stattdessen in einer Umgebungsvariablen, wie im nächsten Schritt gezeigt.
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>"
Führen Sie dies in Ihrem Terminal aus (Terminal unter macOS, Eingabeaufforderung oder PowerShell unter Windows), nicht in einem Browser.
Die folgenden Beispiele verwenden alle dieses Foto. Um ein anderes Bild auszuprobieren, ändern Sie image_url.

Request
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
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.
Um bei Abschluss der Aufgabe benachrichtigt zu werden, anstatt wiederholt abzufragen, streamen Sie die Aufgabe oder verwenden Sie einen Webhook.
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
curl -L "<model_urls.glb from the response above>" -o model.glb

In jedem Plan außer Enterprise bewahrt Meshy die Dateien 3 Tage lang auf. Laden Sie die benötigten Dateien vorher herunter. Siehe Aufbewahrung von Assets.
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
Spielfertiger Charakter
Versehen Sie ein humanoides Netz mit einem Skelett, sodass es bereit ist, in Unity oder Unreal animiert zu werden.
Learn more →Smart-Topology-Netz
Setzen Sie model_type bei Bild zu 3D auf smart-topology, um ein sauberes, spielfertiges Dreiecksnetz zu erhalten.
3D-Druckmodell
Konvertieren Sie ein fertiges Modell in eine mehrfarbige 3MF-Datei, bereit zum Slicen und Drucken.
Learn more →Nächste Schritte
- Durchsuchen Sie alle Endpunkte in der API-Referenz.
- Bevor Sie in den Produktivbetrieb gehen, prüfen Sie Preise, Rate limits und Fehler.
- Folgen Sie schrittweisen Anleitungen im Cookbook.