Guias de mídia

Geração 3D

Crie modelos 3D para download a partir de texto ou imagens

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

Arquivos de modelos 3D para download são mantidos como cópias automáticas por 30 dias, e suas URLs são URLs de mídia de resultado do TokenLab. Registros de tarefas e ativos salvos separadamente seguem seu próprio ciclo de vida. Veja Retenção de dados.

Escolha o tipo de entrada

EntradaObrigatórioCampos opcionaisNotas
Text-to-3Dmodel, promptformat, quality, style, seedIdeal para gerar um novo ativo a partir de uma descrição
Image-to-3Dmodel, image_url ou image; também prompt quando o modelo listarformat, quality, style, seedUse apenas quando o modelo selecionado suportar entrada de imagem

operation é opcional e pode ser text-to-3d ou image-to-3d. Se você omiti-lo, o TokenLab usa image-to-3d quando você envia image ou image_url, e text-to-3d caso contrário. Se você enviá-lo, ele deve corresponder às entradas. Um modelo com text-to-3d aceita prompts; um modelo com image-to-3d aceita entrada de imagem.

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

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

Criar 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": "tripo-h3.1",
    "prompt": "A stylized low-poly robot mascot with clean topology"
  }'

Para image-to-3D, use uma URL https quando a fonte puder ser buscada na internet. Use image em base64 inline apenas em um modelo cujos detalhes listem image; alguns modelos aceitam apenas image_url.

Formatos de saída

  • glb funciona bem para 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 de AR da Apple quando exposto pelo modelo.
  • Valores mais altos de quality podem aumentar o tempo de espera e o custo. Mostre essa opção ao usuário.
  • seed afeta a repetibilidade apenas em modelos que a suportam.

Obter o modelo finalizado

Chame GET /v1/tasks/{id} com o id ou task_id retornado.

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. Faça o download ou armazene em cache 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.

Mantenha o resultado disponível

  • Persista task_id, poll_url, modelo, formato solicitado e seu próprio ID de registro de ativo.
  • Retome a sondagem (polling) 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 dos 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

SintomaCausa provávelCorreção
Resposta de criação não tem URL de ativoA geração 3D é assíncronaFaça polling até o status terminal
Formato solicitado ausenteO modelo não retornou esse formatoRecorra a model_url ou escolha um modelo que suporte o formato
Image-to-3D rejeitadoO modelo selecionado é apenas de texto ou a URL da imagem está inacessívelVerifique os detalhes do modelo e valide a URL
Ativos duplicadosO caminho de repetição recriou a tarefa após o tempo limiteArmazene a identidade da tarefa antes de tentar novamente

Referência da API

TópicoReferência
Criar 3DCriar 3D
Obter Status 3DObter Status 3D
Obter Status da TarefaObter Status da Tarefa
Listar ModelosListar Modelos
Faturamento e PreçosFaturamento e Preços

Nesta página