Guia de migração de v2 para v3
Este documento ajuda você a migrar o código existente de Tripo API v2 para v3.
Migre da V2 para a V3 com a Skill
Você não precisa entender primeiro todas as diferenças entre as APIs. Baixe esta Skill, coloque o arquivo no diretório do projeto que deseja migrar e peça à sua ferramenta de programação com IA para usá-lo. Ela ajudará a encontrar as chamadas V2 no seu projeto e a migrá-las para a V3 passo a passo.
Etapa 1: Baixe a Skill
Você receberá um arquivo chamado SKILL.md. Mantenha o nome do arquivo sem alterações.
Etapa 2: Coloque a Skill no diretório do projeto e use-a
Coloque o arquivo SKILL.md baixado no diretório do projeto que deseja migrar. Depois, abra esse projeto e peça diretamente à IA para usar esta Skill.
Etapa 3: Copie esta mensagem para iniciar a migração
Abra o projeto que deseja migrar. Copie a mensagem completa abaixo e envie-a para sua ferramenta de programação com IA:
Use o arquivo `SKILL.md` no diretório do projeto para migrar a integração da Tripo API deste projeto da V2 para a V3. Primeiro, mostre o que precisa ser alterado. Aguarde minha confirmação e, depois, faça as alterações. Por fim, use a lista de verificação contida no arquivo para garantir que nada tenha sido esquecido.
A ferramenta encontrará primeiro as chamadas V2 e mostrará um plano, para que você não precise procurar em todos os arquivos.
Principais mudanças
1. Alteração básica URL
# v2
https://api.tripo3d.ai/v2/openapi/
# v3
https://openapi.tripo3d.ai/v3/
2. Endpoint universal dividido em endpoints dedicados
v2 usa um único terminal POST /v2/openapi/task e um campo type para distinguir os tipos de tarefas. v3 fornece um terminal dedicado para cada recurso, portanto o campo type não é mais necessário.
// v2
POST /v2/openapi/task
{ "type": "text_to_model", "prompt": "a cat" }
// v3
POST /v3/generation/text-to-model
{ "prompt": "a cat", "model": "v3.1-20260211" }
3. Entradas de arquivo unificadas como o campo input
Em v2, nomes de campo diferentes são usados dependendo da fonte de entrada, como file, file_token, url e object. Em v3, eles são unificados no campo input e o sistema infere automaticamente o tipo de entrada.
// v2 - different field names are required
{ "type": "refine_model", "draft_model_task_id": "123e4567-e89b-42d3-a456-426614174000" }
{ "type": "convert_model", "original_model_task_id": "123e4567-e89b-42d3-a456-426614174000" }
// v3 - use input consistently
{ "input": "123e4567-e89b-42d3-a456-426614174000" }
{ "input": "https://example.com/model.glb" }
{ "input": "file_token_abc123" }
4. Nomes de campos padronizados
| Campo v2 | Campo v3 |
|---|---|
create_time |
created_at |
consumed_credit |
credits_consumed |
5. Divisão de texto para imagem e imagem para imagem
Em v2, texto para imagem e imagem para imagem compartilham o mesmo API. No v3, eles são divididos em endpoints dedicados:
POST /v3/generation/text-to-image- Gere uma imagem a partir de entrada somente de textoPOST /v3/generation/image-to-image– Gere ou edite uma imagem com base em uma imagem de referência
Mapeamento de endpoints
Geração
| Valor do tipo v2 | Ponto final v3 |
|---|---|
text_to_model |
POST /v3/generation/text-to-model |
image_to_model |
POST /v3/generation/image-to-model |
multiview_to_model |
POST /v3/generation/multiview-to-model |
text_to_image |
POST /v3/generation/text-to-image |
generate_image |
POST /v3/generation/image-to-image |
generate_multiview_image |
POST /v3/generation/image-to-multiview |
edit_multiview_image |
POST /v3/generation/edit-multiview |
Processamento de modelo
| Valor do tipo v2 | Ponto final v3 |
|---|---|
refine_model |
POST /v3/models/refine |
convert_model |
POST /v3/models/convert |
import_model |
POST /v3/models/import |
stylize_model |
POST /v3/models/stylize |
texture_model |
POST /v3/models/texture |
Animação
| Valor do tipo v2 | Ponto final v3 |
|---|---|
animate_prerigcheck |
POST /v3/animations/rig-check |
animate_rig |
POST /v3/animations/rig |
animate_retarget |
POST /v3/animations/retarget |
Edição de malha
| Valor do tipo v2 | Ponto final v3 |
|---|---|
mesh_segmentation |
POST /v3/mesh/segment |
mesh_completion |
POST /v3/mesh/complete |
highpoly_to_lowpoly |
POST /v3/mesh/decimate |
Tarefas e Arquivos
| Ponto final v2 | Ponto final v3 |
|---|---|
GET /v2/openapi/task/{task_id} |
GET /v3/tasks/{task_id} |
POST /v2/openapi/upload |
POST /v3/files |
Etapas de migração
Etapa 1: atualize a base URL
# v2
BASE_URL = "https://api.tripo3d.ai/v2/openapi"
# v3
BASE_URL = "https://openapi.tripo3d.ai/v3"
Etapa 2: Substituir endpoints usando a tabela de mapeamento
# v2
response = requests.post(f"{BASE_URL}/task", json={
"type": "text_to_model",
"prompt": "a cat"
})
# v3
response = requests.post(f"{BASE_URL}/generation/text-to-model", json={
"prompt": "a cat",
"model": "v3.1-20260211"
})
Etapa 3: remover o campo type
Em v3, o caminho do endpoint já implica o tipo de tarefa, portanto o corpo da solicitação não precisa mais do campo type.
Etapa 4: Substitua os campos de entrada por input
# v2 - different task types use different field names
payload = {"type": "refine_model", "draft_model_task_id": "123e4567-e89b-42d3-a456-426614174000"}
payload = {"type": "convert_model", "original_model_task_id": "123e4567-e89b-42d3-a456-426614174000"}
# v3 - use input consistently
payload = {"input": "123e4567-e89b-42d3-a456-426614174000"}
Etapa 5: atualizar os nomes dos campos de resposta
# v2
created = task["create_time"]
cost = task["consumed_credit"]
# v3
created = task["created_at"]
cost = task["credits_consumed"]
Etapa 6: testar e validar
- Substitua e teste cada endpoint, um de cada vez
- Verifique se a criação e a pesquisa de tarefas funcionam corretamente
- Confirme se os links para download estão disponíveis
- Verifique se as consultas de dedução de crédito e saldo funcionam corretamente
Notas
- v2 e v3 podem ser executados em paralelo. Recomendamos migrar gradualmente em vez de mudar tudo de uma vez
- API Keys são compartilhados entre v2 e v3. Você não precisa criar novas chaves
- Use o ID retornado na criação de cada tarefa. Verifique a compatibilidade antes de consultar pelo v3 uma tarefa existente do v2.