TokenLab

Worlds

Créer un monde

Crée une tâche de génération de monde World Labs Marble

POST
/v1/worlds/generations

Générez des mondes 3D explorables avec World Labs Marble. Il s'agit d'une API asynchrone : les réponses de création renvoient une identité de tâche. Interrogez GET /v1/tasks/{id} avec l'id de la tâche pour obtenir son statut.

Choisissez un modèle Marble actuellement disponible à l'aide de l'API Models.

Corps de la requête

modelstringpar défaut: marble-1.0

Choisissez un modèle Marble actuellement disponible à l'aide de l'API Models.

promptstring

Prompt textuel pour une génération texte uniquement, ou guidage pour les entrées image et vidéo. Jusqu'à 4000 caractères. Envoyez au moins l'un des champs suivants : world_prompt, prompt, image, image_url, images ou video_url.

world_promptobject

Objet world_prompt natif de World Labs pour les appelants avancés. Les types de prompt pris en charge sont text, image, multi-image et video. Une référence de contenu peut pointer vers un fichier que vous avez téléversé avec Préparer le téléchargement d'un actif multimédia : { "source": "media_asset", "media_asset_id": "..." }.

imagestring

Prompt d'image sous forme de chaîne Base64 ou de data URL.

image_urlstring

Prompt d'image sous forme d'URL.

imagesarray

Plusieurs prompts d'images pour un raccourci de génération multi-images. Fournissez jusqu'à 4 images, chacune étant une URL, une chaîne Base64 ou data URL, ou un objet avec uri, image_url ou url et un nombre azimuth optionnel. Pour le mode de reconstruction natif de World Labs, transmettez world_prompt.type="multi-image" avec reconstruct_images: true et jusqu'à 8 images.

video_urlstring

Prompt vidéo sous forme d'URL.

is_panoboolean | string

Pour les entrées d'image, définissez sur true pour un panorama existant, false pour une image simple normale, ou auto.

seedinteger

Seed optionnel compris entre 0 et 4294967295.

display_namestring

Nom d'affichage optionnel pour le monde généré, jusqu'à 64 caractères.

tagsarray

Tags World Labs optionnels. Fournissez jusqu'à 10 tags, chacun comportant jusqu'à 32 caractères.

permissionobject

Paramètres d'accès et de visibilité optionnels : public, allow_id_access, allowed_readers et allowed_writers. public: true demande un monde visible publiquement.

Réponse

idstring

ID public de la tâche. Interrogez GET /v1/tasks/{id} avec celui-ci.

task_idstring

Alias de l'identifiant de tâche asynchrone.

operation_idstring

ID d'opération World Labs.

poll_urlstring

URL de statut du monde sous /v1/worlds/generations/{id}. Il s'agit d'un endpoint de compatibilité. Interrogez plutôt GET /v1/tasks/{id} avec id.

statusstring

Statut de la tâche : pending, processing, completed ou failed.

world_marble_urlstring

URL du monde Marble généré une fois terminé.

glb_urlstring

URL du maillage de collision GLB lorsqu'il est disponible.

pano_urlstring

URL de l'image panoramique lorsqu'elle est disponible.

Tarification

Consultez l'API Pricing pour connaître les tarifs actuels. Le montant final facturé est indiqué dans vos relevés d'utilisation.

Erreurs

  • 400 invalid_request : aucune entrée de prompt n'a été envoyée, ou un champ est hors limites. param nomme le champ.
  • 400 model_not_found ou unsupported_endpoint : le modèle n'est pas un modèle Marble appelable.
  • 403 media_asset_not_owned ou 404 media_asset_not_found : un media_asset_id dans world_prompt appartient à un autre Workspace ou n'existe pas.
  • 402 : le solde est trop faible pour démarrer la tâche.

Requête

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"    }  }}

Autorisation

BearerAuth
AuthorizationBearer <token>

Authentification par clé API. Créez ou gérez vos clés API dans Dashboard > API > API Keys.

Emplacement: header

En-têtes

X-TokenLab-Delivery-Policy?string

Politique de livraison par requête. Remplace les valeurs par défaut de la clé API et de l'espace de travail. Tente automatiquement TokenLab Verified en premier et peut basculer une fois vers Official uniquement avant la sortie, l'acceptation de la requête ou la création de ressource persistante.

Valeurs possibles

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

Clé optionnelle qui permet de réessayer une requête de création en toute sécurité. Envoyez une nouvelle valeur unique, telle qu'un UUID, pour chaque tâche. Une tentative avec la même clé et le même corps renvoie le résultat de la requête de création initiale, généralement la tâche d'origine, et ne crée, ne distribue ni ne facture une seconde tâche. Un corps différent avec une clé déjà acceptée est rejeté avec 409. Une clé de plus de 255 caractères est ignorée, et la requête ne bénéficie alors d'aucune protection d'idempotence. Voir Réessayer en toute sécurité avec une clé d'idempotence.

Longueur1 <= length <= 255

Corps de la requête

application/json

Réponse

application/json

application/json

application/json

application/json

application/json