TokenLab

Guides médias

Worlds

Créez des mondes Marble explorables à partir de texte, d'images ou de vidéo

Worlds crée un environnement Marble que les utilisateurs peuvent ouvrir et explorer. Si vous avez besoin d'un objet téléchargeable plutôt que d'un environnement, utilisez la génération 3D.

Les fichiers World téléchargeables, tels que les splats, les maillages et les images panoramiques, sont conservés sous forme de copies automatiques de 30 jours avec les URL de résultats média de TokenLab. La page interactive World et les enregistrements World ne le sont pas. Voir Rétention des données.

Inputs And Media Assets

Un monde peut être généré à partir de texte, d'une ou plusieurs images, ou d'une vidéo, selon le modèle. Trouvez les modèles Marble (marble-*) dans GET /v1/models?recommended_for=3d ; leur opération est world-generation. Envoyez au moins une entrée :

InputField
Texteprompt, jusqu'à 4 000 caractères
Une imageimage_url, ou image en Base64 ou une URL de données ; is_pano indique s'il s'agit déjà d'un panorama
Plusieurs imagesimages, jusqu'à 4
Vidéovideo_url
Avancéworld_prompt, un objet prompt natif qui peut référencer un actif média téléchargé

Les champs optionnels sont display_name (jusqu'à 64 caractères), seed, tags (jusqu'à 10) et permission. Les médias réutilisables peuvent être téléchargés une fois et référencés par leur ID d'actif.

L'accès aux médias et aux enregistrements de mondes est vérifié par rapport à l'organisation propriétaire de la clé API. Examinez les options de permission du modèle sélectionné avant de partager un monde ; un actif renvoyé ou une URL de visualisation peut avoir ses propres règles d'accès.

Create And Poll

La réponse de création contient un ID de tâche et généralement une poll_url. Conservez l'ID, puis appelez GET /v1/tasks/{id} avec celui-ci jusqu'à ce que le statut soit completed ou failed. La poll_url de Worlds pointe vers /v1/worlds/generations/{id}, un chemin de compatibilité. Utilisez plutôt /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"
  }'

Interrogez la tâche avec l'id provenant de la réponse de création :

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Manage Completed Worlds

Utilisez POST /v1/worlds/list et GET /v1/worlds/{id} pour les mondes terminés disponibles dans votre compte, et DELETE /v1/worlds/{id} pour en supprimer un. Utilisez GET /v1/tasks/{id} pour les tâches de génération en attente ou échouées. Supprimez uniquement lorsqu'un utilisateur retire intentionnellement le monde généré de votre produit.

Common Pitfalls

  • Ne supposez pas que chaque modèle de monde prend en charge tous les types d'entrée.
  • Maintenez les URL d'images ou de vidéos signées valides assez longtemps pour les tentatives de récupération du service.
  • Stockez l'ID de tâche renvoyé avant de réessayer après un délai d'attente.
  • Utilisez la génération 3D pour les fichiers de modèles téléchargeables plutôt que pour des mondes explorables.

API Reference

TopicReference
Create WorldCréer un monde
Get Task StatusObtenir le statut d'une tâche
Get World Status (compatibility)Obtenir le statut du monde
Prepare Media Asset UploadPréparer l'upload d'un asset média
Get Media AssetRécupérer un media asset
List WorldsLister les mondes
Get WorldObtenir un World
Delete WorldSupprimer un World
Async JobsAsync Jobs
3D Generation Guide3D Generation Guide

Sur cette page