Zum Hauptinhalt springen
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

WorkflowErforderliche EingabeOptionale FelderHinweise
Text-zu-3Dmodel, promptformat, quality, style, seedAm besten geeignet, um ein neues Asset aus einer Beschreibung zu generieren
Bild-zu-3Dmodel, prompt, image oder image_urlformat, quality, style, seedNur verwenden, wenn das ausgewählte Modell die Bild-Eingabe unterstützt
Fragen Sie den Modellkatalog ab, bevor Sie entscheiden, welche Optionen angezeigt werden sollen: 
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"
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": "tripo3d-v2.5",
    "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

SymptomWahrscheinliche UrsacheLösung
Die Antwort beim Erstellen hat keine Asset-URL3D-Generierung ist asynchronAbfragen bis zum terminalen Status
Angefordertes Format fehltModell hat dieses Format nicht zurückgegebenFallback auf model_url oder wählen Sie ein Modell, das das Format unterstützt
Bild-zu-3D abgelehntAusgewähltes Modell ist nur für Text oder Bild-URL ist nicht erreichbarÜberprüfen Sie den Modellvertrag und validieren Sie die URL
Doppelte AssetsDer Wiederholungsweg hat die Aufgabe nach der Zeitüberschreitung neu erstelltSpeichern Sie die Aufgabenidentität, bevor Sie es erneut versuchen

​
API-Referenz

ThemaReferenz
3D erstellenCreate 3D
3D-Status abrufenGet 3D Status
Aufgabenstatus abrufenGet Task Status
Modelle auflistenList Models
Abrechnung & PreiseBilling & Pricing