# Руководство по миграции с v2 на v3

Этот документ поможет вам перенести существующий код с Tripo API v2 на v3.

## Перейдите с V2 на V3 с помощью Skill

Вам не нужно сначала разбираться во всех различиях API. Скачайте этот Skill, поместите файл в каталог проекта, который нужно перенести, и попросите инструмент для программирования на базе ИИ использовать его. Он поможет найти вызовы V2 в вашем проекте и шаг за шагом перенести их на V3.

### Шаг 1: Скачайте Skill

<a class="plugin-download-button" href="/assets/developer/tripo-v2-to-v3-migration/SKILL.md" download="SKILL.md">Скачать</a>

Вы получите файл с именем `SKILL.md`. Не изменяйте имя файла.

### Шаг 2: Поместите Skill в каталог проекта и используйте его

Поместите скачанный `SKILL.md` в каталог проекта, который нужно перенести, затем откройте этот проект и просто попросите ИИ использовать этот Skill.

### Шаг 3: Скопируйте этот запрос, чтобы начать миграцию

Откройте проект, который хотите перенести. Скопируйте весь запрос ниже и отправьте его своему инструменту для программирования на базе ИИ:

```text
Используйте файл `SKILL.md` из каталога проекта, чтобы перенести интеграцию Tripo API этого проекта с V2 на V3. Сначала покажите, что требуется изменить. Дождитесь моего подтверждения, затем внесите изменения. В конце воспользуйтесь контрольным списком в файле, чтобы убедиться, что ничего не пропущено.
```

Инструмент сначала найдет вызовы V2 и покажет вам план, поэтому вам не придется самостоятельно искать их в каждом файле.

## Основные изменения

### 1. Изменение базы URL

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

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

### 2. Универсальная конечная точка разделена на выделенные конечные точки.

v2 использует одну конечную точку `POST /v2/openapi/task` и поле `type` для различения типов задач. v3 предоставляет выделенную конечную точку для каждой возможности, поэтому поле `type` больше не требуется.

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

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

### 3. Входные данные файла объединены в поле `input`.

В v2 используются разные имена полей в зависимости от источника входных данных, например `file`, `file_token`, `url` и `object`. В v3 они объединены в поле `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. Стандартизированные имена полей

| Поле v2 | Поле v3 |
| :-: | :-: |
| `create_time` | `created_at` |
| `consumed_credit` | `credits_consumed` |

### 5. Разделение текста на изображение и изображения на изображение

В v2 процессы преобразования текста в изображение и изображения в изображение используют один и тот же API. В v3 они разделены на выделенные конечные точки:

- `POST /v3/generation/text-to-image` — создать изображение из текстового ввода.
- `POST /v3/generation/image-to-image` — создание или редактирование изображения на основе эталонного изображения.

## Сопоставление конечных точек

### Поколение

| Тип v2 Значение | 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` |

### Обработка модели

| Тип v2 Значение | 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` |

### Анимация

| Тип v2 Значение | v3 Конечная точка |
| :-: | :-: |
| `animate_prerigcheck` | `POST /v3/animations/rig-check` |
| `animate_rig` | `POST /v3/animations/rig` |
| `animate_retarget` | `POST /v3/animations/retarget` |

### Редактирование сетки

| Тип v2 Значение | v3 Конечная точка |
| :-: | :-: |
| `mesh_segmentation` | `POST /v3/mesh/segment` |
| `mesh_completion` | `POST /v3/mesh/complete` |
| `highpoly_to_lowpoly` | `POST /v3/mesh/decimate` |

### Задачи и файлы

| v2 Конечная точка | v3 Конечная точка |
| :-: | :-: |
| `GET /v2/openapi/task/{task_id}` | `GET /v3/tasks/{task_id}` |
| `POST /v2/openapi/upload` | `POST /v3/files` |

## Этапы миграции

### Шаг 1. Обновите базу URL.

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

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

### Шаг 2. Замените конечные точки с помощью таблицы сопоставления

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

### Шаг 3. Удалите поле `type`.

В v3 путь к конечной точке уже подразумевает тип задачи, поэтому в теле запроса больше не требуется поле `type`.

### Шаг 4. Замените поля ввода на `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"}
```

### Шаг 5. Обновите имена полей ответа

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

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

### Шаг 6: Тестирование и проверка

1. Заменяйте и тестируйте каждую конечную точку по одной
2. Убедитесь, что создание задач и опрос работают правильно.
3. Убедитесь, что ссылки для скачивания доступны.
4. Убедитесь, что запросы на вычет кредита и баланс работают правильно

## Примечания

- v2 и v3 могут работать параллельно. Мы рекомендуем переходить постепенно, а не сразу.
- API Keys используются v2 и v3. Вам не нужно создавать новые ключи
- Формат задачи ID остается неизменным. Задачи, созданные в v2, можно запросить в v3.