# Migrationshandbuch von v2 zu v3

Dieses Dokument hilft Ihnen bei der Migration von vorhandenem Code von Tripo API v2 nach v3.

## Mit dem Skill von V2 auf V3 umsteigen

Sie müssen nicht zuerst jeden API-Unterschied verstehen. Laden Sie diesen Skill herunter, legen Sie die Datei im Verzeichnis des zu migrierenden Projekts ab und weisen Sie Ihr KI-Coding-Tool an, sie zu verwenden. Der Skill hilft Ihnen, V2-Aufrufe in Ihrem Projekt zu finden und Schritt für Schritt auf V3 umzustellen.

### Schritt 1: Skill herunterladen

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

Sie erhalten eine Datei namens `SKILL.md`. Ändern Sie den Dateinamen nicht.

### Schritt 2: Skill im Projektverzeichnis ablegen und verwenden

Legen Sie die heruntergeladene `SKILL.md` im Verzeichnis des zu migrierenden Projekts ab. Öffnen Sie anschließend dieses Projekt und weisen Sie die KI direkt an, diesen Skill zu verwenden.

### Schritt 3: Diesen Prompt kopieren und die Migration starten

Öffnen Sie das Projekt, das Sie migrieren möchten. Kopieren Sie den vollständigen Prompt unten und senden Sie ihn an Ihr KI-Coding-Tool:

```text
Verwende die `SKILL.md` im Projektverzeichnis, um die Tripo-API-Integration dieses Projekts von V2 auf V3 umzustellen. Zeige mir zuerst, was geändert werden muss. Warte auf meine Bestätigung und nimm dann die Änderungen vor. Prüfe abschließend anhand der Checkliste in der Datei, dass nichts übersehen wurde.
```

Das Tool sucht zuerst die V2-Aufrufe und zeigt Ihnen einen Plan, sodass Sie nicht jede Datei selbst durchsuchen müssen.

## Wichtige Änderungen

### 1. Basis-URL-Änderung

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

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

### 2. Universeller Endpunkt, aufgeteilt in dedizierte Endpunkte

v2 verwendet einen einzelnen `POST /v2/openapi/task`-Endpunkt und ein `type`-Feld, um Aufgabentypen zu unterscheiden. v3 stellt für jede Funktion einen dedizierten Endpunkt bereit, sodass das Feld `type` nicht mehr erforderlich ist.

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

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

### 3. Dateieingaben vereinheitlicht als `input`-Feld

In v2 werden je nach Eingabequelle unterschiedliche Feldnamen verwendet, z. B. `file`, `file_token`, `url` und `object`. In v3 werden sie unter dem Feld `input` vereinheitlicht, und das System leitet automatisch den Eingabetyp ab.

```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. Standardisierte Feldnamen

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

### 5. Text-zu-Bild- und Bild-zu-Bild-Split

In v2 nutzen Text-zu-Bild und Bild-zu-Bild dasselbe API. In v3 sind sie in dedizierte Endpunkte aufgeteilt:

- `POST /v3/generation/text-to-image` – Generieren Sie ein Bild aus reiner Texteingabe
- `POST /v3/generation/image-to-image` – Erzeugen oder bearbeiten Sie ein Bild basierend auf einem Referenzbild

## Endpunktzuordnung

### Generation

| Wert vom Typ v2 | v3 Endpunkt |
| :-: | :-: |
| `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` |

### Modellverarbeitung

| Wert vom Typ v2 | v3 Endpunkt |
| :-: | :-: |
| `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` |

### Animation

| Wert vom Typ v2 | v3 Endpunkt |
| :-: | :-: |
| `animate_prerigcheck` | `POST /v3/animations/rig-check` |
| `animate_rig` | `POST /v3/animations/rig` |
| `animate_retarget` | `POST /v3/animations/retarget` |

### Netzbearbeitung

| Wert vom Typ v2 | v3 Endpunkt |
| :-: | :-: |
| `mesh_segmentation` | `POST /v3/mesh/segment` |
| `mesh_completion` | `POST /v3/mesh/complete` |
| `highpoly_to_lowpoly` | `POST /v3/mesh/decimate` |

### Aufgaben und Dateien

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

## Migrationsschritte

### Schritt 1: Aktualisieren Sie die Basis URL

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

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

### Schritt 2: Ersetzen Sie Endpunkte mithilfe der Zuordnungstabelle

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

### Schritt 3: Entfernen Sie das `type`-Feld

In v3 impliziert der Endpunktpfad bereits den Aufgabentyp, sodass der Anforderungstext das Feld `type` nicht mehr benötigt.

### Schritt 4: Ersetzen Sie die Eingabefelder durch `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"}
```

### Schritt 5: Antwortfeldnamen aktualisieren

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

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

### Schritt 6: Testen und validieren

1. Ersetzen und testen Sie jeden Endpunkt einzeln
2. Stellen Sie sicher, dass die Aufgabenerstellung und -abfrage ordnungsgemäß funktioniert
3. Bestätigen Sie, dass Download-Links verfügbar sind
4. Überprüfen Sie, ob Guthabenabzugs- und Saldoabfragen korrekt funktionieren

## Notizen

- v2 und v3 können parallel laufen. Wir empfehlen, schrittweise zu migrieren, anstatt alle auf einmal zu wechseln
- API Keys werden von v2 und v3 gemeinsam genutzt. Sie müssen keine neuen Schlüssel erstellen
- Das Format der Aufgabe ID bleibt unverändert. In v2 erstellte Aufgaben können in v3 abgefragt werden