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

# Recast a video with your own avatars using the Percify API

> Recast a 3 to 15 second clip with the Percify API: swap the people for your own avatars, rebuild the scene, or swap an object, keeping the original motion, camera and sound. About $6 for 15 seconds.

Recast takes a short clip and changes who or what is in it while keeping everything that made it work: every movement, head turn, lip movement, the camera and the timing, with the original sound. `POST /v3/recast/v1/jobs` starts a job, and you read the result with `GET /v3/recast/v1/jobs/{id}` or a webhook. Calls need a `pk_live_` key, the same as the rest of the API; see [Authentication](https://docs.percify.io/percify/api-auth.md). From an AI assistant, use the `recast_video` tool on the [MCP server](https://docs.percify.io/mcp-server.md).

```text theme={"system"}
https://api.percify.io/v3/recast/v1
```

| Method | Path | What it does |
| - | - | - |
| `POST` | `/v1/estimate` | Exact price for a clip, free |
| `POST` | `/v1/jobs` | Start a recast |
| `GET` | `/v1/jobs/{id}` | Read a recast |

## Modes

| `mode` | What changes | What you send |
| - | - | - |
| `recast` (default) | The people in the clip become your avatars | `cast`: up to 3 of your avatars |
| `motion_transfer` | The scene and characters are rebuilt; motion, camera and timing stay | `refs` (images of the new look), `cast` and/or `prompt` |
| `object_swap` | One thing is replaced: a character, outfit, product, location or object | `target` (what to replace) and `refs` (the new thing) |

Faces come from **your own avatars**. Make one with [create\_avatar](https://docs.percify.io/mcp-server.md) or the avatars API first. A reference image that shows a real person's face counts as an uploaded likeness, and uploaded likenesses are not accepted at launch.

## Price

| | Credits |
| - | - |
| First frame | 5, flat |
| Video, 720p | 16 per second of clip, rounded up |

**A 15-second recast costs about \$6** (245 credits). It is charged once when the job starts, and refunded in full if the job fails. Anything refused by the checks below is refused before the charge, so it costs nothing. Ask `POST /v1/estimate` for the exact number first:

```bash theme={"system"}
curl -s -X POST https://api.percify.io/v3/recast/v1/estimate \
  -H "Authorization: Bearer $PERCIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"videoUrl":"https://cdn.example.com/clip.mp4"}'
```

```json 201 Response theme={"system"}
{ "success": true, "data": { "seconds": 13, "credits": 213, "perSecond": 16, "firstFrame": 5, "note": "5 credits first frame + 16 credits per second at 720p, charged once, refunded on failure" } }
```

## Start a recast

**videoUrl** `string` *required*

An `https` link to the clip, an `.mp4` from 3 to 15 seconds long. Upload a local file with the upload API first.

**likenessConsent** `boolean` *required*

Must be `true`. It confirms: "I own this video or have the right to edit it, and I have permission from everyone shown and everyone whose likeness I add." It is stored with the time and your IP address.

**mode** `string`

`recast` (default), `motion_transfer` or `object_swap`.

**cast** `object[]`

Up to 3 entries of `{ "avatar": "<your avatar name or id>", "who": "the man on the right" }`. `who` says which person in the clip becomes that avatar; leave it out when there is one person. Required for `recast`.

**refs** `string[]`

Up to 4 `https` images: the new look for `motion_transfer`, the new thing for `object_swap` (required there).

**target** `string`

`object_swap` only, required: what to replace, for example `"the red sneakers"`. At most 120 characters.

**prompt** `string`

Optional description of the new scene or look, at most 400 characters.

**webhook** `string`

Optional `https` URL. It gets one `POST` when the job ends, with event `recast.completed`, signed like every Percify webhook. See [Webhooks](https://docs.percify.io/guides/webhooks.md).

**Idempotency-Key** `string`

Reuse the same value on retries to get the original job back instead of paying again. Kept for 24 hours.

```bash theme={"system"}
curl -s -X POST https://api.percify.io/v3/recast/v1/jobs \
  -H "Authorization: Bearer $PERCIFY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: recast-launch-clip-1" \
  -d '{
    "videoUrl": "https://cdn.example.com/clip.mp4",
    "cast": [
      { "avatar": "Maya", "who": "the woman in front" },
      { "avatar": "Leo", "who": "the man behind her" }
    ],
    "likenessConsent": true
  }'
```

```json 201 Response theme={"system"}
{ "success": true, "data": { "jobId": "3f0c2a71-5b8e-4d19-9a36-7c1e0b4d2f88", "status": "framing", "mode": "recast", "creditsSpent": 213 } }
```

An object swap:

```json theme={"system"}
{ "videoUrl": "https://cdn.example.com/unboxing.mp4", "mode": "object_swap", "target": "the white sneakers", "refs": ["https://cdn.example.com/our-sneaker.jpg"], "likenessConsent": true }
```

## Read a recast

`GET /v3/recast/v1/jobs/{id}` returns:

**data.status** `string`

`framing` → `rendering` → `checking` → `done`. Or `failed` (credits refunded), `refused` (never charged) or `taken_down` (removed after a report).

**data.videoUrl** `string | null`

The finished MP4 when `done`, hosted on cdn.percify.io, with the original sound.

**data.firstFrameUrl** `string | null`

The new first frame the video was built from.

**data.labelled** `boolean | null`

Whether the visible AI label is on the video. It always is for anything other than your own avatar.

**data.code** `string`

On `refused`: `MODERATION_REJECTED` or `CONSENT_REQUIRED`, with a `reason`.

A recast usually takes a few minutes. Poll every 10 to 20 seconds, use the webhook, or call `wait_for_job` with `jobType: "recast"` on the MCP server.

## Limits

* Clips from 3 to 15 seconds, output at 720p.
* Up to 3 avatars and up to 4 reference images.
* The output carries a visible "made with Percify" AI label.

## Safety and consent

Every job is checked before it is charged and again before it is delivered: frames of your clip, your avatars and references, the new first frame, and frames of the finished video.

* **Never allowed:** sexual or nude content of a real or identifiable person, and anything involving someone who may be under 18. These are refused even when the check is unsure, and refused if the check itself cannot run.
* **Real public figures** (celebrities, politicians, athletes, executives, well-known creators) cannot be recast.
* **Faces come from your own avatars.** Recast someone only with their permission.

You may not use Recast to put a person's likeness into a video without their consent, to impersonate anyone, to deceive, or to harass. Accounts that do are closed. Refused requests are logged.

## Report a recast

If you are shown in a video made with Recast, or act for someone who is, report it. No account is needed:

```bash theme={"system"}
curl -s -X POST https://api.percify.io/v3/recast-reports \
  -H "Content-Type: application/json" \
  -d '{"videoUrl":"https://cdn.percify.io/…/recast.mp4","contact":"you@example.com","relationship":"i_am_shown","reason":"This is me and I did not agree to it."}'
```

`relationship` is `i_am_shown`, `representative` or `other`. We review every report and **remove the video within 48 hours** of a valid report. A report we have not resolved within 48 hours is taken down automatically. You can also email [support@percify.io](mailto:support@percify.io) with the link.

## Errors

| Code | When | Charged |
| - | - | - |
| `400` with "consent" (MCP `CONSENT_REQUIRED`) | `likenessConsent` is not `true`, or a reference shows a real face | No |
| `400` with "content moderation" (MCP `MODERATION_REJECTED`) | A public figure, a possible minor, sexual content, or the safety check could not run | No |
| `400` | Clip shorter than 3 or longer than 15 seconds, not `https`, unreadable, or a missing field | No |
| `400` "Not enough credits" | Balance too low; top up at [app.percify.io/billing](https://app.percify.io/billing) | No |
| `404` | Unknown avatar (it must be one of yours) or job id | No |
| `failed` status | Rendering failed, or the finished video failed the checks | Refunded |


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