Medienleitfäden

3D-Generierung

Erstellen Sie herunterladbare 3D-Modelle aus Text oder Bildern

Die 3D-Generierung erfolgt asynchron. POST /v1/3d/generations erstellt einen TokenLab-Task; Antworten mit dem Status „abgeschlossen“ liefern herunterladbare Modell-Assets wie model_url und, sofern verfügbar, formatspezifische URLs.

Herunterladbare 3D-Modelldateien werden als automatische 30-Tage-Kopien gespeichert, und ihre URLs sind TokenLab-Medien-Ergebnis-URLs. Task-Datensätze und separat gespeicherte Assets folgen ihrem eigenen Lebenszyklus. Siehe Datenaufbewahrung.

Wählen Sie den Eingabetyp

EingabeErforderlichOptionale FelderHinweise
Text-to-3Dmodel, promptformat, quality, style, seedAm besten geeignet, um ein neues Asset aus einer Beschreibung zu generieren
Image-to-3Dmodel, image_url oder image; zudem prompt, wenn das Modell dies auflistetformat, quality, style, seedNur verwenden, wenn das ausgewählte Modell Bildeingaben unterstützt

operation ist optional und kann text-to-3d oder image-to-3d sein. Wenn Sie es weglassen, verwendet TokenLab image-to-3d, wenn Sie image oder image_url senden, andernfalls text-to-3d. Wenn Sie es angeben, muss es mit den Eingaben übereinstimmen. Ein Modell mit text-to-3d akzeptiert Prompts; ein Modell mit image-to-3d akzeptiert Bildeingaben.

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 die Details des ausgewählten Modells, bevor Sie image, image_url, format, quality, style oder seed senden.

Erstellen eines 3D-Tasks

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": "A stylized low-poly robot mascot with clean topology"
  }'

Verwenden Sie für Image-to-3D eine https-URL, wenn die Quelle aus dem Internet abgerufen werden kann. Verwenden Sie Inline-Base64-image nur bei einem Modell, dessen Details image auflisten; einige Modelle akzeptieren nur image_url.

Ausgabeformate

  • glb funktioniert gut für Web-Vorschauen.
  • fbx und obj sind nützlich für DCC-Pipelines, wenn das ausgewählte Modell diese unterstützt.
  • usdz ist nützlich für Apple AR-Workflows, wenn es vom Modell bereitgestellt wird.
  • Höhere quality-Werte können die Wartezeit und die Kosten erhöhen. Zeigen Sie diese Auswahl dem Benutzer an.
  • seed beeinflusst die Wiederholbarkeit nur bei Modellen, die dies unterstützen.

Abrufen des fertigen Modells

Rufen Sie GET /v1/tasks/{id} mit der zurückgegebenen id oder task_id auf.

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

Abgeschlossene Tasks 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 zwischen, wenn Benutzer wiederholten Zugriff, Versionsverlauf oder langlebige Downloads benötigen.

Verfügbarkeit des Ergebnisses sicherstellen

  • Speichern Sie task_id, poll_url, Modell, angefordertes Format und Ihre eigene Asset-Datensatz-ID dauerhaft.
  • Setzen Sie das Polling nach einem Seiten-Refresh fort, anstatt einen doppelten Task zu erstellen.
  • Validieren Sie die Größe und Erreichbarkeit des Quellbildes, bevor Sie den Task erstellen.
  • Halten Sie generierte Asset-URLs von öffentlichen Seiten fern, es sei denn, der Benutzer hat die Berechtigung, auf das Asset zuzugreifen.
  • Protokollieren Sie billing_transaction_id, falls vorhanden, für eine spätere Abstimmung.

Häufige Fehler

SymptomWahrscheinliche UrsacheLösung
Erstellungsantwort hat keine Asset-URL3D-Generierung ist asynchronPollen bis zum Endstatus
Angefordertes Format fehltModell hat dieses Format nicht zurückgegebenAuf model_url zurückgreifen oder ein Modell wählen, das das Format unterstützt
Image-to-3D abgelehntAusgewähltes Modell ist nur Text oder Bild-URL ist nicht erreichbarModelldetails prüfen und URL validieren
Doppelte AssetsWiederholungspfad hat den Task nach Timeout neu erstelltTask-Identität vor dem Wiederholen speichern

API-Referenz

ThemaReferenz
3D erstellen3D erstellen
3D-Status abrufen3D-Status abrufen
Task-Status abrufenTask-Status abrufen
Modelle auflistenModelle auflisten
Abrechnung & PreiseAbrechnung & Preise

Auf dieser Seite