# Guida alla migrazione da v2 a v3

Questo documento ti aiuta a migrare il codice esistente da Tripo API v2 a v3.

## Passa da V2 a V3 con lo Skill

Non devi prima capire tutte le differenze tra le API. Scarica questo Skill, inserisci il file nella directory del progetto da migrare e chiedi al tuo strumento di programmazione basato sull'IA di usarlo. Ti aiuterà a trovare le chiamate V2 nel tuo progetto e a migrarle a V3 passo dopo passo.

### Passaggio 1: Scarica lo Skill

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

Otterrai un file chiamato `SKILL.md`. Non modificare il nome del file.

### Passaggio 2: Inserisci lo Skill nella directory del progetto e usalo

Inserisci il file `SKILL.md` scaricato nella directory del progetto da migrare. Poi apri il progetto e chiedi direttamente all'IA di usare questo Skill.

### Passaggio 3: Copia questo messaggio per avviare la migrazione

Apri il progetto che vuoi migrare. Copia il messaggio completo qui sotto e invialo al tuo strumento di programmazione basato sull'IA:

```text
Usa il file `SKILL.md` nella directory del progetto per migrare l'integrazione Tripo API di questo progetto da V2 a V3. Prima mostrami cosa deve cambiare. Attendi la mia conferma, quindi applica le modifiche. Infine, usa la checklist contenuta nel file per assicurarti che non sia stato tralasciato nulla.
```

Lo strumento troverà prima le chiamate V2 e ti mostrerà un piano, così non dovrai cercare in ogni file.

## Grandi cambiamenti

### 1. Modifica base URL

```
# v2
https://api.tripo3d.ai/v2/openapi/

# v3
https://openapi.tripo3d.ai/v3/
```

### 2. Endpoint universale suddiviso in endpoint dedicati

v2 utilizza un singolo endpoint `POST /v2/openapi/task` e un campo `type` per distinguere i tipi di attività. v3 fornisce un endpoint dedicato per ciascuna funzionalità, quindi il campo `type` non è più obbligatorio.

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

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

### 3. Ingressi file unificati come campo `input`

In v2, vengono utilizzati nomi di campo diversi a seconda della sorgente di input, come `file`, `file_token`, `url` e `object`. In v3, sono unificati nel campo `input` e il sistema deduce automaticamente il tipo di input.

```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. Nomi di campo standardizzati

| Campo v2 | Campo v3 |
| :-: | :-: |
| `create_time` | `created_at` |
| `consumed_credit` | `credits_consumed` |

### 5. Divisione testo-immagine e immagine-immagine

In v2, testo-immagine e immagine-immagine condividono lo stesso API. In v3, sono suddivisi in endpoint dedicati:

- `POST /v3/generation/text-to-image` - Genera un'immagine da input di solo testo
- `POST /v3/generation/image-to-image` - Genera o modifica un'immagine basata su un'immagine di riferimento

## Mappatura degli endpoint

### Generazione

| Tipo v2 Valore | Punto finale 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` |

### Elaborazione del modello

| Tipo v2 Valore | Punto finale 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` |

### Animazione

| Tipo v2 Valore | Punto finale v3 |
| :-: | :-: |
| `animate_prerigcheck` | `POST /v3/animations/rig-check` |
| `animate_rig` | `POST /v3/animations/rig` |
| `animate_retarget` | `POST /v3/animations/retarget` |

### Modifica della mesh

| Tipo v2 Valore | Punto finale v3 |
| :-: | :-: |
| `mesh_segmentation` | `POST /v3/mesh/segment` |
| `mesh_completion` | `POST /v3/mesh/complete` |
| `highpoly_to_lowpoly` | `POST /v3/mesh/decimate` |

### Attività e file

| Punto finale v2 | Punto finale v3 |
| :-: | :-: |
| `GET /v2/openapi/task/{task_id}` | `GET /v3/tasks/{task_id}` |
| `POST /v2/openapi/upload` | `POST /v3/files` |

## Passaggi di migrazione

### Passaggio 1: aggiorna la base URL

```python
# v2
BASE_URL = "https://api.tripo3d.ai/v2/openapi"

# v3
BASE_URL = "https://openapi.tripo3d.ai/v3"
```

### Passaggio 2: sostituire gli endpoint utilizzando la tabella di mappatura

```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"
})
```

### Passaggio 3: rimuovere il campo `type`

In v3, il percorso dell'endpoint implica già il tipo di attività, quindi il corpo della richiesta non necessita più del campo `type`.

### Passaggio 4: sostituisci i campi di input con `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"}
```

### Passaggio 5: aggiornare i nomi dei campi di risposta

```python
# v2
created = task["create_time"]
cost = task["consumed_credit"]

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

### Passaggio 6: testare e convalidare

1. Sostituisci e testa ciascun endpoint uno alla volta
2. Verificare che la creazione delle attività e il polling funzionino correttamente
3. Confermare che i collegamenti per il download siano disponibili
4. Verificare che le query sulla detrazione del credito e sul saldo funzionino correttamente

## Note

- v2 e v3 possono funzionare in parallelo. Ti consigliamo di eseguire la migrazione gradualmente invece di effettuare il passaggio tutto in una volta
- API Keys sono condivisi tra v2 e v3. Non è necessario creare nuove chiavi
- Il formato dell'attività ID rimane invariato. Le attività create in v2 possono essere interrogate in v3