---
title: "Create a persona video"
method: POST
path: "/personas/{id}/videos"
tags: ["Personas"]
---

# Create a persona video

`POST /personas/{id}/videos`

## Request

- Base URL: `https://api.cut.pro/api/v1`
- URL: `https://api.cut.pro/api/v1/personas/{id}/videos`
- Auth: API key in header `X-Api-Key`

Starts a video with a saved persona. `type` picks the kind of video; today the only one is `swap`, which keeps the scene, camera, motion and sound of a library video and replaces its main person with the persona. `quality` (default `standard`) and `replace` (default `person`) pick how; `style` (none by default) redraws it in a drawing technique; quote and create with the same `quality` and `style`. `version_id` picks which of the persona's `versions` to use, the current one when left out. Charged per second of the source, plus a small amount per scene where the person appears, even on a workspace with unlimited usage, and refunded automatically if it fails. Picking a `target` never raises the price above the quote.

Price it first with `GET /personas/swap/quote` and send that `credits`: when the server measures a different price it refuses with `409 PRICE_CHANGED` and the right one in `extra`, so nothing is ever charged above what was confirmed.

Responds `202`. Poll `GET /personas/{id}/videos/{videoId}` every 10 seconds until `ready` or `failed`; the result also lands in the library with an `edit_id` for `POST /renders` and `POST /posts`. `VIDEO_IN_PROGRESS` means this persona is already working on the same version with the same video.

## Path parameters

- `id` string, required

## Request body

- object
  - `type` 'swap', required: The kind of video to make; only `swap` is made here.
  - `media_id` string, required: Library video whose person is replaced.
  - `credits` union, required: The price returned by `GET /personas/swap/quote` for this `media_id` and `quality`.
    - string, integer
    - integer: The price returned by `GET /personas/swap/quote` for this `media_id` and `quality`.
  - `quality` 'economy' | 'standard' | 'high': `economy` is `standard` at a lower resolution, upscaled to 1080p, and the cheapest. `standard` follows the persona's traits, up to `video_limits.standard.max_seconds`. `high` also follows the persona's photos, keeps the face closest to them and takes longer videos, at a higher price; prefer it for personas made from face photos.
  - `replace` 'head' | 'person' | 'none': What of the video's main person becomes the persona: `head` changes only the head and hair and keeps the body and outfit, `person` replaces the whole person, body and outfit included, `none` replaces nobody and only applies the `style`, which then is required.
  - `style` 'cel' | 'felt' | 'yarn' | 'sketch' | 'toy' | 'grotesque' | 'painterly' | 'graphic' | 'gouache' | 'sculptural' | 'lowpoly' | 'toon' | 'cinematic' | 'flat' | 'neon' | 'editorial' | 'comic' | 'pixel' | 'plush' | 'embroidery' | 'mosaic' | 'stainedglass' | 'chalk' | 'silent' | 'thermal' | 'hologram': Redraws the whole video, people and scene, in an animation, illustration, material or camera look while keeping its camera and motion, for example `cel` (hand-painted 2D animation), `felt` (felt puppet stop motion), `toy` (rounded toy 3D), `pixel` (pixel art), `stainedglass` (stained glass) or `silent` (1920s silent film). The whole person is replaced, whatever `replace` says, unless it is `none`. Not available at `quality: high` past `video_mid_max_seconds`.
  - `version_id` string: A persona version id from `versions`. Defaults to the current version.
  - `target` union: Picks who becomes the persona: a person seen in the video, or whoever is filming. Defaults to the main person. Refused with `TARGET_UNSUPPORTED` past the end of the video or on high-quality sources longer than `video_mid_max_seconds`, and with `TARGET_NOT_A_PERSON` when nobody is at that spot.
    - object: A person seen in the video.
      - `seconds` number, required: The moment of the source, in seconds, where the person is chosen.
      - `x` number, required: Horizontal center of the person at that moment, 0 at the left edge and 1 at the right.
      - `y` number, required: Vertical center of the person at that moment, 0 at the top and 1 at the bottom.
      - `box` object: The box around the whole person at that moment. Sharper than `x` and `y` alone when people stand close together.
        - `x` number, required: Left edge of the person, 0 to 1 across the picture.
        - `y` number, required: Top edge of the person, 0 to 1 down the picture.
    - object: Whoever is filming.
      - `seconds` number: A moment where whoever films shows their face, if they turn the camera to themselves. Found automatically when left out.
      - `camera` true, required: Replaces whoever holds the camera in a first-person video: their hands, arms and anything of their body in view, and their face wherever the camera turns to them. Nobody new is added to the scene.

## Response `202`

Response for status 202

- object
  - `id` string, required: Persona video id.
  - `status` 'processing', required
  - `credits_charged` number, required: Credits debited now. Refunded automatically if the video fails.

## Other responses

- `400`: Response for status 400
- `402`: Response for status 402
- `404`: Response for status 404
- `409`: Response for status 409
- `502`: Response for status 502

---

[API](https://skmtc.dev/cut/apis/cutpro-api.md) · [All operations](https://skmtc.dev/cut/apis/cutpro-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cut/apis/cutpro-api/revisions/89d0bafe529c?raw)