> For the complete documentation index, see [llms.txt](https://bountyv.gitbook.io/vdocs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bountyv.gitbook.io/vdocs/video-api/videos-wan-reel.md).

# Wan Reel

Swap a face identity into a driving reel on our self-hosted Wan 2.2 Animate — the reel's real motion, scene, and audio are kept.

```
POST /api/v1/videos/wan-reel
```

Asynchronous. Returns a `generation_id` immediately (`202 Accepted`); poll `GET /api/v1/videos/wan-reel/{id}` for the result.

Upload a **face** (the identity) and a **driving reel**. The reel's first frame is recreated with your identity (Seedream i2i), then Wan 2.2 Animate drives it with the reel's real motion, scene, and audio. Charged on successful dispatch; a failed render is refunded automatically.

No saved identity is needed — `face` is a plain image upload.

> Renders take **5–15 minutes** on an H100 depending on reel length and workflow. Poll every 10–20 seconds. SFW only.

## Authentication

`Authorization: Bearer sk_live_...`. See [Authentication](/vdocs/authentication.md).

## Request

**Content-Type:** `multipart/form-data`

| Field                 | Type                  | Required | Default                  | Description                                                                                     |
| --------------------- | --------------------- | -------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `face`                | File                  | ✅        | —                        | Identity photo — the person to swap into the reel. Max 15MB                                     |
| `video`               | File                  | ✅\*      | —                        | Driving reel (`.mp4`). Its motion, scene, and audio are kept. Max 200MB                         |
| `video_url`           | string (URL)          | ✅\*      | —                        | Public URL to the driving reel, used instead of `video` for reels too large for a direct upload |
| `resolution`          | `"720p"` \| `"1080p"` | —        | `720p`                   | Output resolution                                                                               |
| `workflow`            | `"v1"` \| `"v2"`      | —        | `v1`                     | `v1` = face-only swap. `v2` = "dressing" — carries the identity's own outfit (ViTPose + Uni3C)  |
| `preserve_background` | `"true"`              | —        | off                      | `v2` only — REPLACE mode: keep the reel's original background, swap only the person             |
| `fast`                | `"true"`              | —        | off                      | `v2` only — RIFE speed path (\~6–7 min); softer lip-sync on talking clips                       |
| `carry_outfit`        | `"true"`              | —        | off (forced on for `v2`) | `v1` — dress the identity in its own outfit from the face image instead of the reel's clothing  |

\* Either `video` or `video_url` is required.

## Response — submit

```json
{
  "generation_id": "gen_V1StGXR8_Z5",
  "status": "pending",
  "charged_cents": 250,
  "balance_cents": 4750,
  "poll_url": "/api/v1/videos/wan-reel/gen_V1StGXR8_Z5"
}
```

HTTP status: `202 Accepted`.

## Polling

```
GET /api/v1/videos/wan-reel/{id}
```

Poll `poll_url` every 10–20 seconds until `status` is `completed` or `failed`.

**Pending:**

```json
{ "status": "pending" }
```

**Completed:**

```json
{ "status": "completed", "video": "https://.../reel.mp4", "generation_id": "gen_V1StGXR8_Z5" }
```

**Failed** (credits already refunded on the first poll that observes it):

```json
{ "status": "failed", "error": "...", "refunded_cents": 250 }
```

This pipeline uses its own poll route rather than the shared [Job status](/vdocs/video-api/jobs.md) endpoint — see [Job status](/vdocs/video-api/jobs.md) for the `videos/generate` equivalent.

## Example

```bash
# 1. Submit
curl -X POST https://substance-api.com/api/v1/videos/wan-reel \
  -H "Authorization: Bearer sk_live_..." \
  -F "face=@./face.jpg" \
  -F "video=@./reel.mp4" \
  -F "resolution=720p" \
  -F "workflow=v1"

# 2. Poll until completed
curl https://substance-api.com/api/v1/videos/wan-reel/gen_V1StGXR8_Z5 \
  -H "Authorization: Bearer sk_live_..."
```

## Errors

| Status | When                                                                                                                 |
| ------ | -------------------------------------------------------------------------------------------------------------------- |
| `400`  | Missing `face`, missing both `video` and `video_url`, a file over its size limit, or `video_url` couldn't be fetched |
| `401`  | Invalid or missing API key                                                                                           |
| `402`  | Insufficient credits                                                                                                 |
| `403`  | Your account doesn't have the `video` product enabled                                                                |
| `502`  | The render couldn't be started                                                                                       |
| `503`  | Pipeline temporarily offline                                                                                         |

Poll-time errors (generation not found, forbidden) return `404` / `403` respectively. See [Errors](/vdocs/errors.md) for full details.

## Pricing

Billed per call — see [Credits & pricing](/vdocs/account/credits.md) for current rates.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bountyv.gitbook.io/vdocs/video-api/videos-wan-reel.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.