# v2 から v3 への移行ガイド

このドキュメントは、既存のコードを Tripo API v2 から v3 に移行するのに役立ちます。

## Skill を使って V2 から V3 に移行する

最初から API の違いをすべて理解する必要はありません。この Skill をダウンロードして、移行するプロジェクトのディレクトリに置き、AI コーディングツールに使うよう指示してください。プロジェクト内の 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 を使うよう AI に直接指示してください。

### ステップ 3：このプロンプトをコピーして移行を始める

移行したいプロジェクトを開きます。以下のプロンプト全文をコピーして、Skills に対応した AI コーディングツールに送ってください。

```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. 各エンドポイントを一度に 1 つずつ交換してテストします
2. タスクの作成とポーリングが正しく機能することを確認します
3. ダウンロード リンクが利用可能であることを確認する
4. クレジット控除と残高クエリが正しく機能することを確認します

## 注意事項

- v2 と v3 は並行して実行できます。一度にすべて切り替えるのではなく、段階的に移行することをお勧めします
- API Keys は、v2 と v3 の間で共有されます。新しいキーを作成する必要はありません
- タスク ID の形式は変更されません。 v2 で作成されたタスクは、v3 でクエリできます。