Tripo
Tripo H3.1
tripo-h3.1/image-to-3d
Modelo de geração 3D de alto detalhe da Tripo, com suporte para gerar ativos 3D texturizados a partir de prompts de texto, de uma única imagem ou de múltiplas vistas, com número de faces e qualidade de textura ajustáveis e saída de materiais PBR, ideal para a produção de ativos como itens de jogo e visualização de produtos
Experimentar tripo-h3.1/image-to-3d
Entrada
Envie uma foto de um único objeto com fundo limpo como entrada para a geração; são suportados apenas JPG, PNG e WEBP.
Saída
Preços
tripo-h3.1/image-to-3d per model
+ $0.290 geometria mais refinada · se detalhada for selecionado
Visão geral
Destinado a desenvolvedores e equipes de design que precisam gerar rapidamente ativos 3D a partir de uma única foto. Basta fornecer o link HTTPS de uma imagem de objeto com fundo limpo para obter um modelo 3D com geometria e textura opcional, ideal para converter rapidamente fotos de objetos reais em ativos digitais prontos para visualização, renderização ou edição posterior.
Destaques principais
- Geração de modelo 3D a partir de uma única imagem — basta fornecer o link de uma foto de objeto com fundo limpo para iniciar a geração, ideal para digitalizar rapidamente objetos reais ou desenhos de design.
- Controle separado de geometria e textura — é possível desativar simultaneamente textura e PBR para obter apenas a malha geométrica, ou definir separadamente os níveis de qualidade de geometria e textura conforme a finalidade.
- Limite de faces configurável — é possível especificar um número-alvo de faces triangulares entre 1.000 e 1,5 milhão (2 milhões em geometria detalhada), facilitando a adaptação a pipelines downstream com diferentes níveis de precisão.
- Resultados reproduzíveis — tanto a geometria quanto a textura aceitam seed aleatória; combinado com parâmetros fixos, isso facilita a geração repetida e a comparação de resultados.
Descrição das capacidades
Geração de malha 3D a partir de imagem: insira o link HTTPS de uma única foto de objeto e obtenha um modelo 3D; com textura e PBR ambos desativados, obtém-se apenas a malha geométrica, ideal para definir a forma antes do pós-processamento.
Controle do número-alvo de faces: o limite de faces (face_limit) permite definir um número-alvo de faces triangulares entre 1.000 e 1,5 milhão (2 milhões em geometria detalhada); se não for preenchido, o modelo decide de forma adaptativa, facilitando atender às necessidades de precisão de renderização ou de cenários leves.
Alternância de textura e PBR: a textura é ativada por padrão, e o material PBR é gerado por padrão; ao ativar PBR, a textura é gerada obrigatoriamente; somente com textura e PBR ambos desativados resta apenas a geometria, conforme a finalidade downstream.
Alternância de níveis de qualidade: a qualidade de geometria e a qualidade de textura podem ser definidas como padrão ou detalhada (standard / detailed); o nível detalhado proporciona, respectivamente, mais detalhes na malha e texturas de maior resolução.
Orientação e alinhamento de textura: a opção de orientação (orientation) "alinhar à imagem de entrada" (align_image) gira automaticamente o modelo para corresponder à imagem de entrada; o alinhamento de textura (texture_alignment) pode ser ajustado à imagem original ou à geometria.
Cenários de aplicação
- Conversão de fotos de objetos reais em ativos digitais — equipes de e-commerce ou design geram modelos 3D a partir de fotos de objetos segurados na mão e os inserem em páginas de exibição de produtos ou visualizadores 3D para que os usuários possam girar e visualizar.
- Materialização rápida de design conceitual — designers conceituais convertem esboços ou imagens de referência em malhas 3D e as utilizam como ponto de partida de proporção e volume para refinamento em softwares de modelagem.
- Base 3D para materiais de marketing — equipes de marketing geram modelos com textura a partir de imagens de produtos e os importam em fluxos de renderização ou animação para produzir materiais de produtos tridimensionais em peças publicitárias.
- Pré-geração de ativos leves — desenvolvedores definem um número menor de faces e textura padrão para gerar em lote ativos de exibição 3D adequados a dispositivos móveis ou cenários em tempo real.
Limitações e recomendações de escolha
A entrada aceita apenas o link HTTPS de uma única imagem de objeto com fundo limpo; imagens com fundo desorganizado ou com vários objetos no mesmo quadro podem não produzir uma geometria ideal. O número-alvo de faces é limitado entre 1.000 e 1,5 milhão (2 milhões em geometria detalhada) de faces triangulares; especificar um número baixo de faces causa perda de detalhes; com textura e PBR desativados, a saída é uma geometria sem material. As configurações de alinhamento de textura e orientação afetam a aparência final e devem ser escolhidas conforme a imagem de entrada; o resultado gerado não garante correspondência ponto a ponto com a foto.
Novidades
Ver o changelog →- Novo modelo tripo-h3.1/multiview-to-3d disponível: Tripo H3.1 gera modelos 3D a partir de múltiplas vistas
- Novo modelo tripo-h3.1/text-to-3d disponível: Tripo H3.1 texto para 3D
- Novo modelo tripo-h3.1/image-to-3d disponível: Tripo H3.1 geração de 3D a partir de imagem
Perguntas frequentes
Ver todas as perguntas →-
Qual é o limite de faces? É possível chegar a 2 milhões?
Sim, o limite de face_limit é de 2 milhões de triângulos, mas só há suporte real até 2 milhões quando geometry_quality está definido como detailed; com standard, recomenda-se definir dentro de 1,5 milhão. Se face_limit não for informado, o modelo decide o número de faces de forma adaptativa.
-
Como faço para obter primeiro apenas uma geometria sem texturas?
Basta definir texture e pbr como false; quando pbr é true, as texturas são geradas obrigatoriamente. Se precisar de texturas mas não de material PBR, defina texture como true e pbr como false.
-
É necessário ativar parâmetros separados para geometria de alta densidade?
Definir geometry_quality como detailed acrescenta detalhes de malha mais finos e é também o pré-requisito para que a contagem de polígonos possa chegar a 2 milhões; se precisar de texturas mais refinadas, defina texture_quality como detailed. Ambos têm o padrão standard; ative-os apenas conforme os requisitos de close-up do ativo de destino.
-
Como reproduzir os resultados gerados para facilitar a comparação entre diferentes parâmetros?
A geometria e as texturas têm, cada uma, uma seed fixa: model_seed controla a geometria, texture_seed controla as texturas e, na geração de 3D a partir de texto, há ainda image_seed para controlar a imagem conceitual. Ao comparar ajustes de parâmetros, primeiro fixe as seeds e altere apenas um parâmetro, para poder determinar de qual item vem a diferença.
Criar uma tarefa de geração
https://api.hiapi.ai/v1/tasks Cabeçalhos
AuthorizationstringObrigatórioChave de API da conta. Obrigatória em toda requisição. Exemplo: Bearer YOUR_HIAPI_API_KEY. Obter chave de API
Content-TypestringOpcionalO corpo da requisição é sempre interpretado como JSON; se enviado, apenas application/json (charset opcional) é aceito — qualquer outro valor retorna 415. Exemplo: application/json.
Idempotency-KeystringOpcionalChave de idempotência, até 255 bytes. Retries com a mesma chave da mesma conta criam a tarefa apenas uma vez; replays retornam o taskId original.
Em timeouts de rede ou retries automáticos do cliente, a mesma chave cria a tarefa apenas uma vez, sem cobrança duplicada (escopo = a conta da chave de API). Use um identificador de negócio exclusivo (ex.: "order-42"); replays retornam o taskId original e as chaves expiram 24 h após a primeira requisição. A matriz completa de cenários está na introdução da API assíncrona unificada.
Corpo
modelstringObrigatórioValor fixo atual: tripo-h3.1/image-to-3d
routestringOpcionalValor fixo atual: default
inputobjectObrigatório
Objeto de parâmetros de negócio para tripo-h3.1/image-to-3d e a rota default — veja a tabela de parâmetros abaixo.
pbrbooleanOpcionalPadrão: trueControla se o material PBR é gerado; quando definido como true, os mapas de textura também são gerados. Padrão true.
texturebooleanOpcionalPadrão: trueDefine se as texturas são geradas para o modelo, padrão true. Observe que, quando pbr é true, as texturas são geradas obrigatoriamente; apenas quando texture e pbr são ambos definidos como false é gerada uma malha puramente geométrica.
image_urlstringObrigatóriopattern ^https://Endereço HTTPS de uma única foto do objeto, com fundo limpo, usada como imagem de entrada para geração de 3D a partir de imagem.
face_limitintegerOpcionalmin 1000max 2000000Número alvo de triângulos, valor inteiro, intervalo de 1000 a 1500000 (até 2000000 quando geometry_quality=detailed); se omitido, o modelo decide o número de faces de forma adaptativa; o arquivo costuma ser grande, e para exibição web recomenda-se cerca de 50000.
model_seedintegerOpcionalSemente aleatória da geração de geometria, valor inteiro, usada para reproduzir o mesmo resultado geométrico.
orientationstringOpcionalPadrão: "default"Controla a orientação do modelo; align_image gira e alinha automaticamente com base na imagem de entrada. Padrão default.
defaultalign_imagetexture_seedintegerOpcionalSemente aleatória da geração de textura, valor inteiro, usada para reproduzir o mesmo resultado de textura.
texture_qualitystringOpcionalPadrão: "standard"Controla a qualidade da textura; detailed gera texturas de resolução mais alta. Padrão standard.
standarddetailedgeometry_qualitystringOpcionalPadrão: "standard"Controla a qualidade da geometria; detailed adiciona detalhes de malha mais refinados. Padrão standard.
standarddetailedtexture_alignmentstringOpcionalPadrão: "original_image"Controla o modo de alinhamento da textura com a imagem de entrada. Padrão original_image.
original_imagegeometrycallbackobjectOpcional
Configuração de notificação de estado terminal. Se omitida, sem callback: consulte a tarefa por conta própria.
Informe callback.url na criação e o HiAPI fará POST no seu serviço no estado terminal, sem polling. O corpo do callback replica a estrutura do detalhe da tarefa; assinatura, retries e idempotência estão descritos na introdução da API assíncrona unificada.
urlstringObrigatórioObrigatória se callback estiver presente. No estado terminal é enviado um POST para esta URL; deve ser uma URL http(s) válida.
whenstringOpcionalPadrão: "final"Atualmente só há suporte a final — notifica tanto em success quanto em fail.
finalstoragestringOpcionalPadrão: "temp"Nível de armazenamento de artefatos: temp (padrão, ~7 dias) ou persistent (longo prazo, cobrado por tamanho). Saldo insuficiente ou limite excedido ⇒ rebaixamento silencioso para temp; o nível efetivo aparece na resposta de detalhes.
temppersistentExemplos de requisição
# Envia uma tarefa assíncrona; retorna um taskId imediatamente (sem esperar a geração)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "tripo-h3.1/image-to-3d",
"input": {
"pbr": true,
"texture": true,
"image_url": "…",
"orientation": "default",
"texture_quality": "standard",
"geometry_quality": "standard",
"texture_alignment": "original_image"
}
}' const res = await fetch("https://api.hiapi.ai/v1/tasks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "tripo-h3.1/image-to-3d",
input: {
"pbr": true,
"texture": true,
"image_url": "…",
"orientation": "default",
"texture_quality": "standard",
"geometry_quality": "standard",
"texture_alignment": "original_image"
}
}),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } } import os, requests
res = requests.post(
"https://api.hiapi.ai/v1/tasks",
headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
json={
"model": "tripo-h3.1/image-to-3d",
"input": {
"pbr": True,
"texture": True,
"image_url": "…",
"orientation": "default",
"texture_quality": "standard",
"geometry_quality": "standard",
"texture_alignment": "original_image"
}
},
)
print(res.json()) # { code, message, data: { taskId } } 200 OK
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR"
}
} 400 Bad Request
{
"code": 400,
"message": "invalid request",
"data": null,
"error_code": "INVALID_REQUEST"
} Obter detalhes da tarefa
https://api.hiapi.ai/v1/tasks/:id Campos da resposta
taskIdstringObrigatórioID da tarefa, sempre com prefixo tk-hiapi-.
modelstringObrigatórioNome completo resolvido do modelo. Tarefas enviadas com o parâmetro route retornam base@route (ex.: gpt-image-2/text-to-image@ext); caso contrário, igual ao nome enviado.
routestringOpcionalPresente apenas se o parâmetro route explícito foi usado; ecoa o valor enviado.
statusstringObrigatórioEstado da tarefa.
queued Na fila, ainda não iniciada.
handling Em processamento.
archiving Processamento concluído, preparando artefatos.
success Terminal: concluído, artefatos disponíveis (retorna output).
fail Terminal: falha (retorna error).
Após o envio, acompanhe status: success e fail são terminais, os demais não. Faça polling a cada 1–3 s até o estado terminal. Em caso de sucesso, baixe os artefatos em output[].url e transfira antes de expireAt; para retenção longa, use storage: "persistent" na criação.
creatednumberObrigatórioMomento de criação da tarefa (segundos Unix).
completednumberObrigatórioSegundos Unix do estado terminal; 0 enquanto não terminal.
outputarrayOpcional
Presente apenas com status == success. Lista de artefatos — sempre um array; uma tarefa pode retornar vários types ao mesmo tempo (ex.: video + first_frame).
Array [ object ]
Itens do array
urlstringObrigatórioURL do artefato, baixável diretamente.
typestringObrigatórioValores possíveis no momento: video, image, audio, first_frame, last_frame, thumbnail; poderão ser ampliados.
expireAtnumberObrigatórioSegundos Unix de disponibilidade do artefato; baixe ou transfira antes da expiração.
errorobjectOpcional
Presente apenas com status == fail.
codestringObrigatórioCódigo de erro de negócio.
messagestringObrigatórioDescrição do erro.
Exemplos de resposta
Sucesso
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
"model": "happyhorse-1-0",
"status": "success",
"created": 1777282033,
"completed": 1777282099,
"output": [
{
"url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
"type": "video",
"expireAt": 1777886899
}
]
}
} Em processamento (não final)
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "archiving",
"created": 1777282033,
"completed": 0
}
} Falhou
{
"code": 200,
"message": "success",
"data": {
"taskId": "tk-hiapi-...",
"model": "happyhorse-1-0",
"status": "fail",
"created": 1777282033,
"completed": 1777282099,
"error": {
"code": "TASK_FAILED",
"message": "task failed"
}
}
} Artigos
Ver todos os artigos →-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio
-
Guia de uso
Guia de introdução ao Tripo H3.1: três modos de entrada, parâmetros e como escolher o preço
Decisão de integração e controle de custos na geração 3D para desenvolvedores
-
Avaliação comparativa
Comparativo e guia de seleção do Tripo H3.1: como escolher entre os três caminhos de geração 3D e como economizar
A partir do formato de entrada, do refinamento geométrico e das chaves de PBR/textura, faça uma ponderação de preço e capacidade orientada a desenvolvedores