# 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

<a class="plugin-download-button" href="/assets/developer/tripo-v2-to-v3-migration/SKILL.md" download="SKILL.md">Baixar</a>

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:

```text
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