> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 从旧版迁移到 V1

> 将已有 Viggle 集成从旧版 API 迁移到 V1。

<Warning>
  **旧版 API 已弃用。** 新接入必须使用 V1；旧接口仅用于迁移过渡。
</Warning>

## 接口映射

| 旧版                                | V1                                                                           |
| --------------------------------- | ---------------------------------------------------------------------------- |
| `POST /api/characters/preprocess` | `POST /v1/characters`                                                        |
| `/api/scenes/*`                   | `/v1/motions/*`                                                              |
| `POST /api/render`                | `POST /v1/renders`（`multipart/form-data`）                                    |
| `GET /api/render/{job_id}`        | `GET /v1/videos/{video_id}`，与 H3 视频生成统一查询；`GET /v1/renders/{render_id}` 已停用。 |
| `DELETE /api/render/{job_id}`     | 已移除，V1 没有公开的客户端取消渲染操作。                                                       |
| `GET /api/credits`                | `GET /v1/credits`                                                            |
| `/api/extract/static-bin`         | `POST /v1/characters`，设置 `type=vsplat`；同时保留渲染能力使用 `all`。                     |
| `/api/extract/dynamic-fbx`        | `POST /v1/motions`，设置 `type=glb`；同时保留渲染素材使用 `all`。                           |

V1 的 3D 提取不再使用独立 `/v1/avatars` 或 `/v1/animations` 资源，而是同一角色、动作资源中的 `type`、`vsplat`/`glb` 属性。输出通过[角色导出](/zh/v1/api-reference/characters/export)或[动作导出](/zh/v1/api-reference/motions/export)获取，无需追踪旧版独立的 `avatar_`/`anim_` 提取资源。

提取控制参数大多沿用原名，但不再公开 vsplat 模型选择（旧 `model` 由服务内部决定），也不再有 `fp` 字段。调用者仅用 `render_thumbnail` 决定是否生成缩略图，渲染来源和姿势由内部决定。输出改为单个 `.vsplat` 文件（`vsplat_url`），替代 `bin_url`/`stripped_bin_url`。动作提取继续支持 `enable_smoothing`、`target_fps`、`task_id`。角色来源使用 `image`、`image_url` 或复用的 `character_id`；动作来源使用 `motion_video`、`motion_video_url` 或复用的 `motion_id`。创建资源时使用新 `type` 参数，复用 ID 渲染时遵循渲染接口的参数约定。

## 响应映射

| 旧版                             | V1                                                                               |
| ------------------------------ | -------------------------------------------------------------------------------- |
| `scene_id`                     | `motion_id`                                                                      |
| `job_id`                       | 以 `render_` 开头的 `id`                                                             |
| `complete`                     | `ready`                                                                          |
| `cdn_url`                      | `video_url`                                                                      |
| `mask_cdn_url`                 | `alpha_url`                                                                      |
| 顶层错误字段                         | 嵌套 `error`，包含 `code`、`message`、`retryable`、`request_id`、`details`、`remediation`。 |
| `bin_url` / `stripped_bin_url` | 通过 `GET /v1/characters/{character_id}/export` 获取 `vsplat_url`。                   |
| `fbx_url`                      | 已移除。动作仅导出 `glb_url`，使用 `download_type=mixamo` 或 `metahuman` 选择骨架。                |

## 建议迁移顺序

1. 更新请求路径和表单字段，包含角色、动作创建时的 `type`。
2. 保存 V1 带前缀的 ID（`char_`、`mot_`、`render_`），避免混用 UUID 与任务 ID；3D 提取不再维护独立的旧版 `avatar_`/`anim_` 资源。
3. 轮询处理 `ready`、`failed`、`cancelled`，并移除客户端主动取消渲染的依赖。
4. 错误处理改用 `error.code`（大写下划线形式）、`error.retryable` 和 `error.remediation`。
5. 确认透明输出使用 `alpha_url`。
6. 3D 下载从旧 avatar/animation 查询接口迁移到角色、动作各自的 `/export` 接口。