Worlds

Welt erstellen

Erstellt eine World Labs Marble-Weltgenerierungsaufgabe

POST
/v1/worlds/generations

Generieren Sie erkundbare 3D-Welten mit World Labs Marble. Dies ist eine asynchrone API: Erstellungsantworten geben eine Task-Identität zurück. Rufen Sie GET /v1/tasks/{id} mit der Task-id ab, um den Status zu prüfen.

Wählen Sie ein derzeit verfügbares Marble-Modell über die Models API.

Request-Body

modelstringStandard: marble-1.0

Wählen Sie ein derzeit verfügbares Marble-Modell über die Models API.

promptstring

Text-Prompt für reine Textgenerierung oder Anleitung für Bild- und Videoeingaben. Bis zu 4000 Zeichen. Senden Sie mindestens eines der folgenden Felder: world_prompt, prompt, image, image_url, images oder video_url.

world_promptobject

Natives World Labs world_prompt-Objekt für fortgeschrittene Aufrufer. Unterstützte Prompt-Typen sind text, image, multi-image und video. Eine Inhaltsreferenz kann auf eine Datei verweisen, die Sie mit Vorbereitung des Uploads von Media Assets hochgeladen haben: { "source": "media_asset", "media_asset_id": "..." }.

imagestring

Base64- oder Data-URL-Bild-Prompt.

image_urlstring

Bild-URL-Prompt.

imagesarray

Mehrere Bild-Prompts für die verkürzte Multi-Bild-Generierung. Geben Sie bis zu 4 Bilder an, jeweils als URL, Base64- oder Data-URL-Zeichenkette oder als Objekt mit uri, image_url oder url sowie einer optionalen azimuth-Zahl. Für den nativen World Labs-Rekonstruktionsmodus übergeben Sie world_prompt.type="multi-image" mit reconstruct_images: true und bis zu 8 Bildern.

video_urlstring

Video-URL-Prompt.

is_panoboolean | string

Geben Sie bei Bildeingaben true für ein vorhandenes Panorama an, false für ein normales Einzelbild oder auto.

seedinteger

Optionaler Seed von 0 bis 4294967295.

display_namestring

Optionaler Anzeigename für die generierte Welt, bis zu 64 Zeichen.

tagsarray

Optionale World Labs-Tags. Geben Sie bis zu 10 Tags an, jeweils bis zu 32 Zeichen.

permissionobject

Optionale Sichtbarkeits- und Zugriffseinstellungen: public, allow_id_access, allowed_readers und allowed_writers. public: true fordert eine öffentlich sichtbare Welt an.

Antwort

idstring

Öffentliche Task-ID. Fragen Sie GET /v1/tasks/{id} damit ab.

task_idstring

Alias für den asynchronen Task-Identifier.

operation_idstring

World Labs Operations-ID.

poll_urlstring

Welt-Status-URL unter /v1/worlds/generations/{id}. Dies ist ein Kompatibilitäts-Endpunkt. Fragen Sie stattdessen GET /v1/tasks/{id} mit id ab.

statusstring

Task-Status: pending, processing, completed oder failed.

world_marble_urlstring

URL für die generierte Marble-Welt nach Fertigstellung.

glb_urlstring

Collider-Mesh-GLB-URL, sofern verfügbar.

pano_urlstring

Panoramabild-URL, sofern verfügbar.

Preise

Aktuelle Tarife finden Sie in der Pricing API. Der endgültig abgerechnete Betrag wird in Ihren Nutzungsdaten ausgewiesen.

Fehler

  • 400 invalid_request: Es wurde keine Prompt-Eingabe übermittelt oder ein Feld liegt außerhalb des gültigen Bereichs. param benennt das Feld.
  • 400 model_not_found oder unsupported_endpoint: Das Modell ist kein aufrufbares Marble-Modell.
  • 403 media_asset_not_owned oder 404 media_asset_not_found: Eine media_asset_id in world_prompt gehört zu einem anderen Workspace oder existiert nicht.
  • 402: Das Guthaben ist zu niedrig, um den Task zu starten.

Anfrage

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"
  }'
{  "id": "string",  "task_id": "string",  "operation_id": "string",  "status": "pending",  "poll_url": "string",  "world_id": "string",  "world_marble_url": "string",  "model_url": "string",  "glb_url": "string",  "pano_url": "string",  "thumbnail_url": "string",  "caption": "string",  "error": "string",  "error_details": {    "projection_version": 0,    "status": 400,    "message": "string",    "type": "string",    "code": "string",    "param": "string",    "retryable": true,    "upstream": {      "source": "string",      "code": "string",      "message": "string",      "param": "string"    }  }}

Autorisierung

BearerAuth
AuthorizationBearer <token>

API-Key-Authentifizierung. Erstellen oder verwalten Sie API-Keys unter Dashboard > API > API Keys.

Ort: header

Header

X-TokenLab-Delivery-Policy?string

Zustellungsrichtlinie pro Anfrage. Überschreibt die API-Key- und Workspace-Standardeinstellungen. Versucht automatisch zuerst TokenLab Verified und kann vor der Ausgabe, der Annahme der Anfrage oder der Erstellung persistenter Ressourcen einmalig auf Official umstellen.

Zulässige Werte

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Optionaler Schlüssel, der eine Erstellungsanfrage sicher für Wiederholungsversuche macht. Senden Sie für jede Aufgabe einen neuen eindeutigen Wert, wie z. B. eine UUID. Ein Wiederholungsversuch mit demselben Schlüssel und demselben Body gibt das Ergebnis der ursprünglichen Erstellungsanfrage zurück, in der Regel die ursprüngliche Aufgabe, und erstellt, versendet oder berechnet keine zweite Aufgabe. Ein abweichender Body mit einem bereits akzeptierten Schlüssel wird mit 409 abgelehnt. Ein Schlüssel mit mehr als 255 Zeichen wird ignoriert, und die Anfrage verfügt dann über keinen Idempotenz-Schutz. Siehe Sichere Wiederholungsversuche mit einem Idempotenz-Schlüssel.

Länge1 <= length <= 255

Anfragekörper

application/json

Antwort

application/json

application/json

application/json

application/json

application/json