Worlds

Criar Mundo

Cria uma tarefa de geração de mundo Marble do World Labs

POST
/v1/worlds/generations

Gere mundos 3D exploráveis com o World Labs Marble. Esta é uma API assíncrona: as respostas de criação retornam uma identidade de tarefa. Consulte GET /v1/tasks/{id} com o id da tarefa para verificar o status.

Escolha um modelo Marble disponível atualmente usando a API de Modelos.

Corpo da Requisição

modelstringpadrão: marble-1.0

Escolha um modelo Marble disponível atualmente usando a API de Modelos.

promptstring

Prompt de texto para geração apenas de texto, ou orientação para entradas de imagem e vídeo. Até 4000 caracteres. Envie pelo menos um dos seguintes: world_prompt, prompt, image, image_url, images ou video_url.

world_promptobject

Objeto world_prompt nativo do World Labs para chamadas avançadas. Os tipos de prompt suportados são text, image, multi-image e video. Uma referência de conteúdo pode apontar para um arquivo que você enviou com Preparar Upload de Ativo de Mídia: { "source": "media_asset", "media_asset_id": "..." }.

imagestring

Prompt de imagem em Base64 ou data URL.

image_urlstring

Prompt de URL de imagem.

imagesarray

Múltiplos prompts de imagem para geração rápida de múltiplas imagens. Forneça até 4 imagens, cada uma sendo uma URL, uma string Base64 ou data URL, ou um objeto com uri, image_url ou url e um número azimuth opcional. Para o modo de reconstrução nativo do World Labs, passe world_prompt.type="multi-image" com reconstruct_images: true e até 8 imagens.

video_urlstring

Prompt de URL de vídeo.

is_panoboolean | string

Para entradas de imagem, defina true para um panorama existente, false para uma imagem única normal, ou auto.

seedinteger

Seed opcional de 0 a 4294967295.

display_namestring

Nome de exibição opcional para o mundo gerado, até 64 caracteres.

tagsarray

Tags opcionais do World Labs. Forneça até 10 tags, cada uma com até 32 caracteres.

permissionobject

Configurações opcionais de visibilidade e acesso: public, allow_id_access, allowed_readers e allowed_writers. public: true solicita um mundo visível publicamente.

Resposta

idstring

ID público da tarefa. Use-o para consultar GET /v1/tasks/{id}.

task_idstring

Alias do identificador da tarefa assíncrona.

operation_idstring

ID da operação do World Labs.

poll_urlstring

URL de status do mundo em /v1/worlds/generations/{id}. Este é um endpoint de compatibilidade. Em vez disso, consulte GET /v1/tasks/{id} com o id.

statusstring

Status da tarefa: pending, processing, completed ou failed.

world_marble_urlstring

URL para o mundo Marble gerado quando concluído.

glb_urlstring

URL do GLB da malha de colisão quando disponível.

pano_urlstring

URL da imagem panorâmica quando disponível.

Preços

Consulte a API de Preços para ver as taxas atuais. O valor final faturado é exibido em seus registros de uso.

Erros

  • 400 invalid_request: nenhum prompt foi enviado ou um campo está fora do intervalo. param nomeia o campo.
  • 400 model_not_found ou unsupported_endpoint: o modelo não é um modelo Marble chamável.
  • 403 media_asset_not_owned ou 404 media_asset_not_found: um media_asset_id em world_prompt pertence a outro Workspace ou não existe.
  • 402: o saldo é insuficiente para iniciar a tarefa.

Requisição

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

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

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

Chave opcional que torna uma requisição de criação segura para novas tentativas. Envie um novo valor único, como um UUID, para cada tarefa. Uma nova tentativa com a mesma chave e o mesmo corpo retorna o resultado da requisição de criação original, geralmente a tarefa original, e não cria, despacha ou cobra uma segunda tarefa. Um corpo diferente com uma chave que já foi aceita é rejeitado com 409. Uma chave com mais de 255 caracteres é ignorada e a requisição não terá proteção de idempotência. Veja Tente novamente com segurança usando uma chave de idempotência.

Comprimento1 <= length <= 255

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json