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
| Eingabe | Erforderlich | Optionale Felder | Hinweise |
|---|---|---|---|
| Text-to-3D | model, prompt | format, quality, style, seed | Am besten geeignet, um ein neues Asset aus einer Beschreibung zu generieren |
| Image-to-3D | model, image_url oder image; zudem prompt, wenn das Modell dies auflistet | format, quality, style, seed | Nur 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
glbfunktioniert gut für Web-Vorschauen.fbxundobjsind nützlich für DCC-Pipelines, wenn das ausgewählte Modell diese unterstützt.usdzist 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. seedbeeinflusst 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
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Erstellungsantwort hat keine Asset-URL | 3D-Generierung ist asynchron | Pollen bis zum Endstatus |
| Angefordertes Format fehlt | Modell hat dieses Format nicht zurückgegeben | Auf model_url zurückgreifen oder ein Modell wählen, das das Format unterstützt |
| Image-to-3D abgelehnt | Ausgewähltes Modell ist nur Text oder Bild-URL ist nicht erreichbar | Modelldetails prüfen und URL validieren |
| Doppelte Assets | Wiederholungspfad hat den Task nach Timeout neu erstellt | Task-Identität vor dem Wiederholen speichern |
API-Referenz
| Thema | Referenz |
|---|---|
| 3D erstellen | 3D erstellen |
| 3D-Status abrufen | 3D-Status abrufen |
| Task-Status abrufen | Task-Status abrufen |
| Modelle auflisten | Modelle auflisten |
| Abrechnung & Preise | Abrechnung & Preise |