Guias de mídia
Worlds
Crie mundos Marble exploráveis a partir de texto, imagens ou vídeo
Worlds cria um ambiente Marble que as pessoas podem abrir e explorar. Se você precisar de um objeto para download em vez de um ambiente, use a geração 3D.
Arquivos de World para download, como splats, meshes e imagens panorâmicas, são mantidos como cópias automáticas de 30 dias com URLs de mídia da TokenLab. A página interativa de World e os registros de World não são. Veja Retenção de dados.
Entradas e Ativos de Mídia
Um mundo pode começar a partir de texto, uma ou mais imagens ou vídeo, dependendo do modelo. Encontre os modelos Marble (marble-*) em GET /v1/models?recommended_for=3d; a operação deles é world-generation. Envie pelo menos uma entrada:
| Entrada | Campo |
|---|---|
| Texto | prompt, até 4.000 caracteres |
| Uma imagem | image_url, ou image como Base64 ou uma data URL; is_pano indica se já é um panorama |
| Várias imagens | images, até 4 |
| Vídeo | video_url |
| Avançado | world_prompt, um objeto de prompt nativo que pode referenciar um ativo de mídia enviado |
Os campos opcionais são display_name (até 64 caracteres), seed, tags (até 10) e permission. Mídias reutilizáveis podem ser enviadas uma vez e referenciadas pelo seu ID de ativo.
O acesso a mídias e registros de mundo é verificado em relação à organização proprietária da API key. Revise as opções de permission do modelo selecionado antes de compartilhar um mundo; um ativo retornado ou URL de visualizador pode ter suas próprias regras de acesso.
Criar e Consultar (Poll)
A resposta de criação contém um ID de tarefa e, geralmente, uma poll_url. Guarde o ID e, em seguida, chame GET /v1/tasks/{id} com ele até que o status seja completed ou failed. A poll_url de Worlds aponta para /v1/worlds/generations/{id}, um caminho de compatibilidade. Use /v1/tasks/{id} em vez disso.
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"
}'Consulte (poll) a tarefa com o id da resposta de criação:
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Gerenciar Worlds Concluídos
Use POST /v1/worlds/list e GET /v1/worlds/{id} para mundos concluídos disponíveis em sua conta, e DELETE /v1/worlds/{id} para remover um. Use GET /v1/tasks/{id} para tarefas de geração pendentes ou com falha. Exclua apenas quando o usuário remover intencionalmente o mundo gerado do seu produto.
Erros Comuns
- Não presuma que todo modelo de mundo suporta todo tipo de entrada.
- Mantenha as URLs de imagem ou vídeo assinadas válidas por tempo suficiente para novas tentativas de busca do serviço.
- Armazene o ID da tarefa retornado antes de tentar novamente após um timeout.
- Use a geração 3D para arquivos de modelo para download em vez de mundos exploráveis.
Referência da API
| Tópico | Referência |
|---|---|
| Criar World | Criar World |
| Obter Status da Tarefa | Obter Status da Tarefa |
| Obter Status do World (compatibilidade) | Obter Status do World |
| Preparar Envio de Ativo de Mídia | Preparar Envio de Ativo de Mídia |
| Obter Ativo de Mídia | Obter Ativo de Mídia |
| Listar Worlds | Listar Worlds |
| Obter World | Obter World |
| Excluir World | Excluir World |
| Trabalhos Assíncronos | Trabalhos Assíncronos |
| Guia de Geração 3D | Guia de Geração 3D |