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 :
| Input | Field |
|---|---|
| Texte | prompt, jusqu'à 4 000 caractères |
| Une image | image_url, ou image en Base64 ou une URL de données ; is_pano indique s'il s'agit déjà d'un panorama |
| Plusieurs images | images, jusqu'à 4 |
| Vidéo | video_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
| Topic | Reference |
|---|---|
| Create World | Créer un monde |
| Get Task Status | Obtenir le statut d'une tâche |
| Get World Status (compatibility) | Obtenir le statut du monde |
| Prepare Media Asset Upload | Préparer l'upload d'un asset média |
| Get Media Asset | Récupérer un media asset |
| List Worlds | Lister les mondes |
| Get World | Obtenir un World |
| Delete World | Supprimer un World |
| Async Jobs | Async Jobs |
| 3D Generation Guide | 3D Generation Guide |