Skip to Content
Cut.ProDocs
AI characters

Get a persona video

Returns one persona video. Poll it every 10 seconds while status is processing; download_url is set once ready.

Authorization

apiKey
headerX-Api-Key<token>

Path Parameters

id*string
videoId*string

Response Body

Response for status 200

application/json
  1. response
id*string
type*string

What kind of video this is. swap replaces the person in a library video with the persona; product is a product ad the persona talks in, made on the web app.

Default"swap"
Value in"swap""product""motion""control"
quality*string

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.

Value in"economy""standard""high"
replace*string

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.

Value in"head""person""none"
style*|

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.

Value in"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"null
status*string
Value in"processing""ready""failed"
version_id*|

The persona version (from the persona's versions) whose photo the video was made from.

duration_seconds*number

Measured duration of the source video, which is what was priced.

credits_charged*number

Credits debited for this video. Refunded automatically when it fails.

edit_id*|

The edit of the result, for POST /renders and POST /posts. A video comes without one: POST /generations/{id}/edit with this video's id makes it, and it is set here from then on.

download_url*|

Signed URL of the resulting MP4, valid for six hours. Set once ready; once handed out, the video counts as downloaded and its credits can no longer be asked back.

thumbnail_url*|

Signed URL of the cover image, valid for six hours.

expected_seconds*|

Expected seconds from created_at until the video is ready, refined as the job advances. Only while processing.

error_code*|

Why the last generation failed, null otherwise: COPYRIGHT_BLOCKED (the scene looks like copyrighted material), REAL_FACES_BLOCKED (a real face is too prominent), SAFETY_BLOCKED (the provider's content rules) and MEDIA_REJECTED (refused for another reason); for any refusal change the traits, the photos or the video. MEDIA_FAILED and MEDIA_UNAVAILABLE (generation broke, retry), INSUFFICIENT_CREDITS, TIMEOUT, OUTPUT_CHECK_FAILED (the video did not keep the persona on the right person even after one free redo; try another video or pick the person), TARGET_NOT_A_PERSON (nobody was at the spot picked as target; pick a person). Credits of a failed generation are refunded automatically.

Default"MEDIA_REJECTED"
Value in"MEDIA_REJECTED""COPYRIGHT_BLOCKED""REAL_FACES_BLOCKED""SAFETY_BLOCKED""MEDIA_FAILED""MEDIA_UNAVAILABLE""INSUFFICIENT_CREDITS""TIMEOUT""OUTPUT_CHECK_FAILED""TARGET_NOT_A_PERSON"null
feedback*|
Value in"up""down"null
feedback_reason*|

Set with a down vote; one of the video feedback reasons.

created_at*string
GET
/personas/{id}/videos/{videoId}
Example Request
curl -X GET 'https://api.cut.pro/api/v1/personas/string/videos/string'
Example Response
{  "id": "string",  "type": "swap",  "quality": "economy",  "replace": "head",  "style": "cel",  "status": "processing",  "version_id": "string",  "duration_seconds": 0,  "credits_charged": 0,  "edit_id": "string",  "download_url": "string",  "thumbnail_url": "string",  "expected_seconds": 0,  "error_code": "MEDIA_REJECTED",  "feedback": "up",  "feedback_reason": "string",  "created_at": "string"}

Create a persona video POST

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, scenes of the person included, 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, and `POST /generations/{id}/edit` with the video's `id` gives the `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.

Read a product from its page link POST

Free. Reads a product page (most online stores, Shopee and Amazon Brazil) and returns its name, description, price and brand, and keeps up to 3 of its photos, whose ids go in `product.photo_ids` of `POST /personas/{id}/shots`. `partial` is `true` when the price or the photos did not come. `PRODUCT_NOT_READABLE` means the page could not be read (Mercado Livre and TikTok Shop never are): upload the photos with `POST /personas/{id}/shots/photos` and write the fields yourself. Up to 5 reads per minute.