Medienleitfäden
Worlds
Erstellen Sie erkundbare Marble-Welten aus Text, Bildern oder Videos
Worlds erstellt eine Marble-Umgebung, die Benutzer öffnen und erkunden können. Wenn Sie anstelle einer Umgebung ein herunterladbares Objekt benötigen, verwenden Sie die 3D-Generierung.
Herunterladbare World-Dateien, wie Splats, Meshes und Panoramabilder, werden als automatische 30-Tage-Kopien mit TokenLab Media-Result-URLs gespeichert. Die interaktive World-Seite und World-Datensätze werden nicht gespeichert. Siehe Datenaufbewahrung.
Eingaben und Medien-Assets
Eine Welt kann je nach Modell aus Text, einem oder mehreren Bildern oder einem Video erstellt werden. Die Marble-Modelle (marble-*) finden Sie unter GET /v1/models?recommended_for=3d; deren Operation lautet world-generation. Senden Sie mindestens eine Eingabe:
| Eingabe | Feld |
|---|---|
| Text | prompt, bis zu 4.000 Zeichen |
| Ein Bild | image_url oder image als Base64 oder Data-URL; is_pano gibt an, ob es sich bereits um ein Panorama handelt |
| Mehrere Bilder | images, bis zu 4 |
| Video | video_url |
| Erweitert | world_prompt, ein natives Prompt-Objekt, das auf ein hochgeladenes Medien-Asset verweisen kann |
Optionale Felder sind display_name (bis zu 64 Zeichen), seed, tags (bis zu 10) und permission. Wiederverwendbare Medien können einmal hochgeladen und über ihre Asset-ID referenziert werden.
Der Zugriff auf Medien und World-Datensätze wird gegen die Organisation geprüft, der der API-Key gehört. Überprüfen Sie die permission-Optionen des ausgewählten Modells, bevor Sie eine Welt teilen; ein zurückgegebenes Asset oder eine Viewer-URL kann eigene Zugriffsregeln haben.
Erstellen und Abfragen (Poll)
Die Antwort der Erstellung enthält eine Task-ID und normalerweise eine poll_url. Speichern Sie die ID und rufen Sie dann GET /v1/tasks/{id} damit auf, bis der Status completed oder failed lautet. Die poll_url von Worlds verweist auf /v1/worlds/generations/{id}, einen Kompatibilitätspfad. Verwenden Sie stattdessen /v1/tasks/{id}.
curl -X POST "https://api.tokenlab.sh/v1/worlds/generations" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "marble-1.1",
"prompt": "A quiet coastal town at sunset with narrow alleys and warm lights"
}'Fragen Sie den Task mit der id aus der Antwort der Erstellung ab:
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Verwalten abgeschlossener Welten
Verwenden Sie POST /v1/worlds/list und GET /v1/worlds/{id} für abgeschlossene Welten, die in Ihrem Konto verfügbar sind, und DELETE /v1/worlds/{id}, um eine zu entfernen. Verwenden Sie GET /v1/tasks/{id} für ausstehende oder fehlgeschlagene Generierungs-Tasks. Löschen Sie nur, wenn der Benutzer die generierte Welt absichtlich aus Ihrem Produkt entfernt.
Häufige Fehlerquellen
- Gehen Sie nicht davon aus, dass jedes World-Modell jeden Eingabetyp unterstützt.
- Halten Sie signierte Bild- oder Video-URLs lange genug gültig, damit der Dienst Wiederholungsversuche (Retries) durchführen kann.
- Speichern Sie die zurückgegebene Task-ID, bevor Sie nach einem Timeout einen erneuten Versuch unternehmen.
- Verwenden Sie die 3D-Generierung für herunterladbare Modelldateien anstelle von erkundbaren Welten.
API-Referenz
| Thema | Referenz |
|---|---|
| Welt erstellen | Welt erstellen |
| Task-Status abrufen | Task-Status abrufen |
| World-Status abrufen (Kompatibilität) | World-Status abrufen |
| Upload von Medien-Assets vorbereiten | Upload von Medien-Assets vorbereiten |
| Medien-Asset abrufen | Medien-Asset abrufen |
| Welten auflisten | Welten auflisten |
| Welt abrufen | Welt abrufen |
| Welt löschen | Welt löschen |
| Asynchrone Jobs | Asynchrone Jobs |
| 3D-Generierungs-Guide | 3D-Generierungs-Guide |