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:

EingabeFeld
Textprompt, bis zu 4.000 Zeichen
Ein Bildimage_url oder image als Base64 oder Data-URL; is_pano gibt an, ob es sich bereits um ein Panorama handelt
Mehrere Bilderimages, bis zu 4
Videovideo_url
Erweitertworld_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

ThemaReferenz
Welt erstellenWelt erstellen
Task-Status abrufenTask-Status abrufen
World-Status abrufen (Kompatibilität)World-Status abrufen
Upload von Medien-Assets vorbereitenUpload von Medien-Assets vorbereiten
Medien-Asset abrufenMedien-Asset abrufen
Welten auflistenWelten auflisten
Welt abrufenWelt abrufen
Welt löschenWelt löschen
Asynchrone JobsAsynchrone Jobs
3D-Generierungs-Guide3D-Generierungs-Guide

Auf dieser Seite