Schnellstart

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 nicht erneut einsehen, nachdem Sie den Bildschirm verlassen haben. 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.

2Eine Bild-zu-3D-Aufgabe erstellen

Sende ein Bild an Bild zu 3D. Um stattdessen von einem Text-Prompt oder mehreren Fotos auszugehen, verwende Text zu 3D oder Multi-Bild zu 3D.

Speichere deinen Schlüssel zunächst in einer Umgebungsvariablen:

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

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

Copy image URL

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 normalerweise einige Minuten. Rufen Sie die Aufgabe über denselben 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 an Sekunden, die im Retry-After-Header angegeben ist.

Typische Verarbeitungszeiten und wie lange Sie warten sollten, bevor Sie abbrechen, finden Sie unter Task lifecycle.

curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
  -H "Authorization: Bearer ${MESHY_API_KEY}"

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

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

4Lade dein Modell herunter

Die Dateien befinden sich in model_urls der vorherigen Antwort. Jedes Format (GLB, FBX, OBJ, USDZ und STL) verfügt über eine signierte URL, die für eine begrenzte Zeit gültig ist. Du kannst die URL auch in deinen Browser einfügen, um die Datei herunterzuladen.

curl -L "<model_urls.glb from the response above>" -o model.glb

Alles zusammenfügen

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

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

Explore common workflows

Next steps

• Durchsuchen Sie jeden Endpunkt in der API-Referenz.
• Bevor Sie in Produktion gehen, prüfen Sie Preise, Ratenbegrenzungen und Fehler.
• Folgen Sie den Schritt-für-Schritt-Anleitungen im Cookbook.