---
title: "Save or rename a persona"
method: POST
path: "/personas/{id}/save"
tags: ["Personas"]
---

# Save or rename a persona

`POST /personas/{id}/save`

## Request

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

Approves the current photo and names the persona, which can then be used in videos. On a persona already saved it only renames it. The photo can still be regenerated or edited later, as new versions. `CARD_NOT_READY` means a draft whose photo is not `ready` yet.

## Path parameters

- `id` string, required

## Request body

- object
  - `name` string, required

## Response `200`

Response for status 200

- object
  - `id` string, required
  - `name` string, required: Empty until the persona is saved.
  - `status` 'draft' | 'ready', required
  - `chips` object, required: One option per trait group. `GET /personas/catalog` lists every option and the defaults.
    - `vibe` 'natural' | 'bold' | 'eccentric', required
    - `gender` 'female' | 'male' | 'androgynous', required
    - `age` '18_24' | '25_34' | '35_44' | '45_59' | '60_plus', required
    - `origin` 'latin' | 'african' | 'european' | 'east_asian' | 'south_asian' | 'middle_eastern' | 'indigenous' | 'mixed', required
    - `skin` 'very_light' | 'light' | 'medium' | 'olive' | 'brown' | 'dark', required
    - `eyes` 'brown' | 'hazel' | 'green' | 'blue' | 'gray' | 'amber' | 'ice_blue', required
    - `hair_style` 'buzz' | 'short' | 'long_straight' | 'long_wavy' | 'curly' | 'coily' | 'braids' | 'bald' | 'bob' | 'pixie' | 'bowl' | 'mullet' | 'mohawk' | 'afro' | 'dreadlocks' | 'pompadour' | 'slicked_back' | 'high_bun' | 'pigtails' | 'beehive' | 'perm' | 'shag', required
    - `hair_color` 'black' | 'brown' | 'blonde' | 'red' | 'gray' | 'dyed' | 'platinum' | 'white' | 'pink' | 'blue' | 'green' | 'purple' | 'two_tone' | 'highlights', required
    - `facial_hair` 'photo' | 'none' | 'stubble' | 'full_beard' | 'long_beard' | 'goatee' | 'moustache' | 'handlebar' | 'pencil', required
    - `face` 'none' | 'dimples' | 'high_cheekbones' | 'full_lips' | 'thick_brows' | 'unibrow' | 'gap_teeth' | 'strong_jaw' | 'hooked_nose' | 'button_nose' | 'jug_ears' | 'eye_bags' | 'cleft_chin', required
    - `body` 'photo' | 'slim' | 'average' | 'athletic' | 'curvy' | 'plus_size' | 'muscular' | 'lanky', required
    - `outfit` 'photo' | 'basic' | 'streetwear' | 'sporty' | 'y2k' | 'goth' | 'punk' | 'suit' | 'retro_70s' | 'aerobics_80s' | 'grunge' | 'preppy' | 'boho' | 'workwear' | 'cowboy' | 'skater' | 'minimalist' | 'glam' | 'techwear' | 'beach', required
    - `accessory` 'photo' | 'none' | 'sunglasses' | 'cap' | 'beanie' | 'bucket_hat' | 'cowboy_hat' | 'bandana' | 'headband' | 'headphones' | 'gold_chain' | 'pearl_necklace' | 'hoop_earrings' | 'scarf' | 'crossbody_bag', required
    - `mark` 'none' | 'glasses' | 'freckles' | 'beauty_mark' | 'nose_piercing' | 'hand_tattoo' | 'hair_streak' | 'septum_ring' | 'face_tattoo' | 'brow_scar' | 'brow_slits' | 'gold_grill' | 'braces' | 'vitiligo' | 'ear_piercings' | 'face_gems' | 'bleached_brows', required
  - `uses_face_photos` boolean, required: `true` when the persona was made from reference photos: the face, skin, eyes and hair come from them.
  - `preset_id` string, nullable, required: The ready-made character this persona started from. Such a persona stays that character: `chips` are ignored on regenerate, a `note` still edits it.
  - `image_status` 'generating' | 'ready' | 'failed', required
  - `error_code` 'MEDIA_REJECTED' | 'COPYRIGHT_BLOCKED' | 'REAL_FACES_BLOCKED' | 'SAFETY_BLOCKED' | 'MEDIA_FAILED' | 'MEDIA_UNAVAILABLE' | 'INSUFFICIENT_CREDITS' | 'TIMEOUT' | 'OUTPUT_CHECK_FAILED', nullable, required: 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). Credits of a failed generation are refunded automatically.
  - `image_url` string, nullable, required: Signed URL of the persona photo (close-up and full body side by side). Valid for one hour.
  - `eta` object, nullable, required: Only while `image_status` is `generating`.
    - `started_at` string, required: ISO 8601 timestamp of when this generation started.
    - `expected_seconds` number, nullable, required: Typical duration of a generation like this one, `null` until there is history to estimate from.
  - `versions` object[], required: Every photo the persona has had, newest first, up to 30. Each generation or edit that finishes adds one and makes it current.
    - `id` string, required: Pass it to `POST /personas/{id}/versions/{versionId}/restore` to go back to this photo.
    - `current` boolean, required: `true` for the photo the persona uses now.
    - `image_url` string, nullable, required: Signed URL of this version's photo, valid for one hour.
    - `face_url` string, nullable, required: Signed URL of this version's close-up portrait, valid for one hour.
    - `feedback` 'up' | 'down', nullable, required: `up` liked, `down` disliked, `null` not rated.
    - `feedback_reason` string, nullable, required: Set with a `down` vote; one of the photo feedback reasons.
    - `created_at` string, required

## Other responses

- `404`: Response for status 404
- `409`: Response for status 409

---

[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)