Skip to Content
Cut.ProDocs
AI characters

Create a persona

Creates a draft persona and starts generating its photo: a close-up portrait and a full-body shot of the same person. Credits are charged now (see GET /personas/catalog), even on a workspace with unlimited usage, and refunded if the photo fails.

With face_ids the persona keeps the identity of the person in the photos, and only the traits listed in face_photo_groups are applied.

Responds 202 with image_status: generating. Poll GET /personas/{id} every 5 seconds until it is ready or failed.

Authorization

apiKey
headerX-Api-Key<token>

Request Body

  1. body
chips*

One option per trait group. GET /personas/catalog lists every option and the defaults.

face_ids?array<string>

Ids from POST /personas/faces, uploaded in the last 24 hours.

Items1 <= items <= 6

Response Body

Response for status 202

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

Empty until the persona is saved.

status*string
Value in"draft""ready"
chips*

One option per trait group. GET /personas/catalog lists every option and the defaults.

uses_face_photos*boolean

true when the persona was made from reference photos: the face, skin, eyes and hair come from them.

preset_id*|

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*string
Value in"generating""ready""failed"
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
image_url*|

Signed URL of the persona photo (close-up and full body side by side). Valid for one hour.

eta*|

Only while image_status is generating.

versions*array<>

Every photo the persona has had, newest first, up to 30. Each generation or edit that finishes adds one and makes it current.

POST
/personas
Example Request
curl -X POST 'https://api.cut.pro/api/v1/personas' \  -H 'Content-Type: application/json' \  -d '{  "chips": {    "vibe": "natural",    "gender": "female",    "age": "18_24",    "origin": "latin",    "skin": "very_light",    "eyes": "brown",    "hair_style": "buzz",    "hair_color": "black",    "facial_hair": "photo",    "face": "none",    "body": "photo",    "outfit": "photo",    "accessory": "photo",    "mark": "none"  }}'
Example Response
{  "id": "string",  "name": "string",  "status": "draft",  "chips": {    "vibe": "natural",    "gender": "female",    "age": "18_24",    "origin": "latin",    "skin": "very_light",    "eyes": "brown",    "hair_style": "buzz",    "hair_color": "black",    "facial_hair": "photo",    "face": "none",    "body": "photo",    "outfit": "photo",    "accessory": "photo",    "mark": "none"  },  "uses_face_photos": true,  "preset_id": "string",  "image_status": "generating",  "error_code": "MEDIA_REJECTED",  "image_url": "string",  "eta": {    "started_at": "string",    "expected_seconds": 0  },  "versions": [    {      "id": "string",      "current": true,      "image_url": "string",      "face_url": "string",      "feedback": "up",      "feedback_reason": "string",      "created_at": "string"    }  ]}