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
| Entrada | Obrigatório | Campos opcionais | Notas |
|---|---|---|---|
| Text-to-3D | model, prompt | format, quality, style, seed | Ideal para gerar um novo ativo a partir de uma descrição |
| Image-to-3D | model, image_url ou image; também prompt quando o modelo listar | format, quality, style, seed | Use 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
glbfunciona bem para visualizações na web.fbxeobjsã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
qualitypodem aumentar o tempo de espera e o custo. Mostre essa opção ao usuário. seedafeta 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_idquando presente para reconciliação posterior.
Erros comuns
| Sintoma | Causa provável | Correção |
|---|---|---|
| Resposta de criação não tem URL de ativo | A geração 3D é assíncrona | Faça polling até o status terminal |
| Formato solicitado ausente | O modelo não retornou esse formato | Recorra a model_url ou escolha um modelo que suporte o formato |
| Image-to-3D rejeitado | O modelo selecionado é apenas de texto ou a URL da imagem está inacessível | Verifique os detalhes 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 e Preços | Faturamento e Preços |