Tripo3D

Guia de migração de v2 para v3

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

Baixar

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.

JSON
// v2
POST /v2/openapi/task
{ "type": "text_to_model", "prompt": "a cat" }

// v3
POST /v3/generation/text-to-model
{ "prompt": "a cat" }

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.

JSON
// v2 - different field names are required
{ "type": "refine_model", "draft_model_task_id": "task_abc123" }
{ "type": "convert_model", "original_model_task_id": "task_abc123" }

// v3 - use input consistently
{ "input": "task_abc123" }
{ "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 texto
  • POST /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

Python
# 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

Python
# 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"
})

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

Python
# v2 - different task types use different field names
payload = {"type": "refine_model", "draft_model_task_id": "task_abc123"}
payload = {"type": "convert_model", "original_model_task_id": "task_abc123"}

# v3 - use input consistently
payload = {"input": "task_abc123"}

Etapa 5: atualizar os nomes dos campos de resposta

Python
# v2
created = task["create_time"]
cost = task["consumed_credit"]

# v3
created = task["created_at"]
cost = task["credits_consumed"]

Etapa 6: testar e validar

  1. Substitua e teste cada endpoint, um de cada vez
  2. Verifique se a criação e a pesquisa de tarefas funcionam corretamente
  3. Confirme se os links para download estão disponíveis
  4. 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
  • O formato da tarefa ID permanece inalterado. Tarefas criadas em v2 podem ser consultadas em v3