> ## 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.

# Migrate from Legacy to V1

> Move an existing Viggle integration from the Legacy API to V1.

<Warning>
  **Legacy is deprecated.** New integrations must use V1. Keep the old endpoint only while you complete this migration.
</Warning>

## Endpoint mapping

| Legacy | 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}` (unified with H3 and character-animation generations; `GET /v1/renders/{render_id}` is retired) |
| `DELETE /api/render/{job_id}` | *(removed — Render cancellation is not a published V1 operation)* |
| `GET /api/credits` | `GET /v1/credits` |
| `/api/extract/static-bin` | `POST /v1/characters` with `type=vsplat` (or `all` to keep the render) |
| `/api/extract/dynamic-fbx` | `POST /v1/motions` with `type=glb` (or `all` to keep the render) |

There is no separate `/v1/avatars` or `/v1/animations` resource in V1 — 3D extraction is a property (`type`, `vsplat`/`glb`) of the same Character/Motion asset used for 2D renders, and its output is fetched from [`GET /v1/characters/{character_id}/export`](/v1/api-reference/characters/export) or [`GET /v1/motions/{motion_id}/export`](/v1/api-reference/motions/export) instead of a standalone `avatar_`/`anim_` resource.

The extraction controls keep mostly the same names in V1, with a few changes: there is no caller-facing vsplat model selection (Legacy's `model` field is gone — the service chooses internally) or `fp` field; callers only choose whether to generate a thumbnail with `render_thumbnail`, while its render source and pose are selected internally; and the output is a single `.vsplat` file (`vsplat_url`) instead of `bin_url`/`stripped_bin_url`. Motion extraction accepts `enable_smoothing`, `target_fps`, and `task_id` unchanged. Only the source fields change: use `image`, `image_url`, or `character_id` for the character, and `motion_video`, `motion_video_url`, or `motion_id` for the motion — both alongside the new `type` field.

## Response mapping

| Legacy | V1 |
| - | - |
| `scene_id` | `motion_id` |
| `job_id` | `id` with a `render_` prefix |
| `complete` | `ready` |
| `cdn_url` | `video_url` |
| `mask_cdn_url` | `alpha_url` |
| top-level error fields | nested `error` object with `code`, `message`, `retryable`, `request_id`, `details`, `remediation` |
| `bin_url` / `stripped_bin_url` | `vsplat_url`, from `GET /v1/characters/{character_id}/export` |
| `fbx_url` | `mixamo_url`/`metahuman_url`/`metahuman_body_url` from `GET /v1/motions/{motion_id}/export?download_type=fbx` (`download_type=glb` for the GLB equivalents) |

## Recommended migration sequence

1. Update request paths and form-field names, including the new `type` field on Character/Motion creation.
2. Store V1 prefixed IDs (`char_`, `mot_`, `render_`) instead of mixing UUIDs and job IDs. There is no separate `avatar_`/`anim_` family to track.
3. Update polling to check for `ready`, `failed`, and `cancelled` — and stop relying on client-triggered cancellation, since V1 has none.
4. Update error handling to use `error.code` (now `SCREAMING_SNAKE_CASE`) and `error.retryable`/`error.remediation`.
5. Verify transparent-output consumers use `alpha_url`.
6. If you fetch 3D output, switch from `GET /v1/avatars/{avatar_id}` / `GET /v1/animations/{animation_id}` to `GET /v1/characters/{character_id}/export` / `GET /v1/motions/{motion_id}/export`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.