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:

EntradaCampo
Textoprompt, até 4.000 caracteres
Uma imagemimage_url, ou image como Base64 ou uma data URL; is_pano indica se já é um panorama
Várias imagensimages, até 4
Vídeovideo_url
Avançadoworld_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ópicoReferência
Criar WorldCriar World
Obter Status da TarefaObter Status da Tarefa
Obter Status do World (compatibilidade)Obter Status do World
Preparar Envio de Ativo de MídiaPreparar Envio de Ativo de Mídia
Obter Ativo de MídiaObter Ativo de Mídia
Listar WorldsListar Worlds
Obter WorldObter World
Excluir WorldExcluir World
Trabalhos AssíncronosTrabalhos Assíncronos
Guia de Geração 3DGuia de Geração 3D

Nesta página