3D-Generierung - TokenLab

Die 3D-Generierung ist asynchron. POST /v1/3d/generations erstellt eine TokenLab-Aufgabe; abgeschlossene Statusantworten geben herunterladbare Modell-Assets wie model_url zurück und, wenn verfügbar, format-spezifische URLs.

Wählen Sie den Eingabetyp

Workflow	Erforderliche Eingabe	Optionale Felder	Hinweise
Text-zu-3D	`model`, `prompt`	`format`, `quality`, `style`, `seed`	Am besten geeignet, um ein neues Asset aus einer Beschreibung zu generieren
Bild-zu-3D	`model`, `prompt`, `image` oder `image_url`	`format`, `quality`, `style`, `seed`	Nur verwenden, wenn das ausgewählte Modell die Bild-Eingabe unterstützt

Fragen Sie den Modellkatalog ab, bevor Sie entscheiden, welche Optionen angezeigt werden sollen: Verwenden Sie für diesen Endpoint den Eingabetyp statt eines operation-Felds. Modell-Metadata melden 3D-Fähigkeiten als text-to-3d und/oder image-to-3d; 3d-generation ist kein öffentlicher Request-operation-Wert.

curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"

Aktuelle Tripo-Beispiele sind tripo-h3.1 fuer hochwertige Text/Image-to-3D-Workflows und tripo-p1.0 fuer produktionsnahe 3D-Asset-Erzeugung. Verwenden Sie die Models API, um Eingabetyp und Ausgabeformat zu bestaetigen. Gehen Sie nicht davon aus, dass jedes 3D-Modell beide Eingabetypen oder jedes Ausgabeformat unterstützt. Überprüfen Sie den Vertrag des ausgewählten Modells, bevor Sie image, image_url, format, quality, style oder seed senden.

Erstellen Sie eine 3D-Aufgabe

curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo-h3.1",
    "prompt": "Ein stilisierter Low-Poly-Roboter-Maskottchen mit sauberer Topologie",
    "format": "glb",
    "quality": "standard"
  }'

Für Bild-zu-3D verwenden Sie, wenn möglich, eine öffentliche image_url. Verwenden Sie inline/base64 image nur, wenn Ihr Client absichtlich private Medien sendet und Ihr Backend auf größere Anforderungsinhalte vorbereitet ist.

Auswahl der Ausgabeformate

glb ist normalerweise die sicherste Standardoption für Webvorschauen.
fbx und obj sind nützlich für DCC-Pipelines, wenn das ausgewählte Modell sie unterstützt.
usdz ist nützlich für Apple AR-Workflows, wenn es vom Modell bereitgestellt wird.
Höhere quality-Werte können Latenz und Kosten erhöhen. Stellen Sie sie als explizite Benutzeroptionen zur Verfügung, nicht als versteckte Standardwerte.
seed ist nur dann nützlich für Reproduzierbarkeit, wenn das Modell es berücksichtigt.

Abfragen und Speichern von Assets

Verwenden Sie zuerst die zurückgegebene poll_url. Wenn Ihr Client eine feste Route benötigt, verwenden Sie GET /v1/tasks/{id}.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Abgeschlossene Aufgaben geben model_url zurück und können glb_url, fbx_url, obj_url oder usdz_url enthalten. Laden Sie das ausgewählte Asset herunter oder speichern Sie es in Ihrem eigenen Produkt, wenn Benutzer wiederholten Zugriff, Versionshistorie oder langfristige Downloads benötigen.

Produktions-Checkliste

Speichern Sie task_id, poll_url, Modell, angefordertes Format und Ihre eigene Asset-Aufzeichnungs-ID.
Setzen Sie das Abfragen nach einer Seitenaktualisierung fort, anstatt eine doppelte Aufgabe zu erstellen.
Validieren Sie die Größe und Erreichbarkeit des Quellbildes, bevor Sie die Aufgabe erstellen.
Halten Sie generierte Asset-URLs von öffentlichen Seiten fern, es sei denn, der Benutzer hat die Berechtigung, auf das Asset zuzugreifen.
Zeichnen Sie billing_transaction_id auf, wenn vorhanden, zur späteren Abrechnung.

Häufige Fehler

Symptom	Wahrscheinliche Ursache	Lösung
Die Antwort beim Erstellen hat keine Asset-URL	3D-Generierung ist asynchron	Abfragen bis zum terminalen Status
Angefordertes Format fehlt	Modell hat dieses Format nicht zurückgegeben	Fallback auf `model_url` oder wählen Sie ein Modell, das das Format unterstützt
Bild-zu-3D abgelehnt	Ausgewähltes Modell ist nur für Text oder Bild-URL ist nicht erreichbar	Überprüfen Sie den Modelldetails und validieren Sie die URL
Doppelte Assets	Der Wiederholungsweg hat die Aufgabe nach der Zeitüberschreitung neu erstellt	Speichern Sie die Aufgabenidentität, bevor Sie es erneut versuchen

API-Referenz

Thema	Referenz
3D erstellen	Create 3D
3D-Status abrufen	Get 3D Status
Aufgabenstatus abrufen	Get Task Status
Modelle auflisten	List Models
Abrechnung & Preise	Billing & Pricing

​Wählen Sie den Eingabetyp

​Erstellen Sie eine 3D-Aufgabe

​Auswahl der Ausgabeformate

​Abfragen und Speichern von Assets

​Produktions-Checkliste

​Häufige Fehler

​API-Referenz