Geração 3D - TokenLab

A geração 3D é assíncrona. POST /v1/3d/generations cria uma tarefa TokenLab; respostas de status concluído retornam ativos de modelo para download, como model_url e, quando disponíveis, URLs específicas de formato.

Escolha O Tipo De Entrada

Fluxo de Trabalho	Entrada obrigatória	Campos opcionais	Notas
Texto-para-3D	`model`, `prompt`	`format`, `quality`, `style`, `seed`	Melhor para gerar um novo ativo a partir de uma descrição
Imagem-para-3D	`model`, `prompt`, `image` ou `image_url`	`format`, `quality`, `style`, `seed`	Use apenas quando o modelo selecionado suportar entrada de imagem

Consulte o catálogo de modelos antes de decidir quais opções expor:

curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
  -H "Authorization: Bearer sk-your-api-key"

Não assuma que todo modelo 3D suporta ambos os tipos de entrada ou todos os formatos de saída. Verifique o contrato do modelo selecionado antes de enviar image, image_url, format, quality, style ou seed.

Crie Uma Tarefa 3D

curl https://api.tokenlab.sh/v1/3d/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo3d-v2.5",
    "prompt": "Um mascote robô estilizado em low-poly com topologia limpa",
    "format": "glb",
    "quality": "standard"
  }'

Para imagem-para-3D, use um image_url público sempre que possível. Use image inline/base64 apenas quando seu cliente enviar intencionalmente mídia privada e seu backend estiver preparado para corpos de solicitação maiores.

Opções De Formato De Saída

glb é geralmente o padrão mais seguro para pré-visualizações na web.
fbx e obj são úteis para pipelines DCC quando o modelo selecionado os suporta.
usdz é útil para fluxos de trabalho AR da Apple quando exposto pelo modelo.
Valores de quality mais altos podem aumentar a latência e o custo. Exponha-os como escolhas explícitas do usuário, não como padrões ocultos.
seed é útil para reprodutibilidade apenas quando o modelo o respeita.

Consulte E Armazene Ativos

Use o poll_url retornado primeiro. Se seu cliente precisar de uma rota fixa, use GET /v1/tasks/{id}.

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

Tarefas concluídas retornam model_url e podem incluir glb_url, fbx_url, obj_url ou usdz_url. Baixe ou armazene o ativo selecionado em seu próprio produto se os usuários precisarem de acesso repetido, histórico de versões ou downloads de longa duração.

Lista De Verificação De Produção

Persista task_id, poll_url, modelo, formato solicitado e seu próprio ID de registro de ativo.
Retome a consulta após a atualização da página, em vez de criar uma tarefa duplicada.
Valide o tamanho e a acessibilidade da imagem de origem antes de criar a tarefa.
Mantenha as URLs de ativos gerados fora de páginas públicas, a menos que o usuário tenha permissão para acessar o ativo.
Registre billing_transaction_id quando presente para reconciliação posterior.

Erros Comuns

Sintoma	Causa provável	Correção
A resposta de criação não tem URL de ativo	A geração 3D é assíncrona	Consulte até o status terminal
Formato solicitado ausente	O modelo não retornou esse formato	Retorne para `model_url` ou escolha um modelo que suporte o formato
Imagem-para-3D rejeitada	O modelo selecionado é apenas texto ou a URL da imagem é inacessível	Verifique o contrato do modelo e valide a URL
Ativos duplicados	O caminho de repetição recriou a tarefa após o tempo limite	Armazene a identidade da tarefa antes de tentar novamente

Referência da API

Tópico	Referência
Criar 3D	Criar 3D
Obter Status 3D	Obter Status 3D
Obter Status da Tarefa	Obter Status da Tarefa
Listar Modelos	Listar Modelos
Faturamento & Preços	Faturamento & Preços

​Escolha O Tipo De Entrada

​Crie Uma Tarefa 3D

​Opções De Formato De Saída

​Consulte E Armazene Ativos

​Lista De Verificação De Produção

​Erros Comuns

​Referência da API