AI personas

Read the catalogCopy Anchor Link

GET /personas/catalog lists every trait option, the defaults, the prices and the limits of a source video.

curl https://api.cut.pro/api/v1/personas/catalog \
  -H "X-Api-Key: $CUTPRO_API_KEY"

Create the personaCopy Anchor Link

Send one option per trait in chips. The photo starts generating and the call answers 202.

curl -X POST https://api.cut.pro/api/v1/personas \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chips": { "vibe": "natural", "gender": "female", "age": "25_34", "origin": "latin", "skin": "medium", "eyes": "brown", "hair_style": "long_wavy", "hair_color": "brown", "facial_hair": "none", "face": "none", "body": "average", "outfit": "basic", "accessory": "none", "mark": "freckles" } }'

To keep the identity of a real person, first upload photos of the user's own face (multipart/form-data, the user must be 18 or older) and pass their ids in face_ids. Only the traits in face_photo_groups still apply.

curl -X POST https://api.cut.pro/api/v1/personas/faces \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -F "photo=@selfie.jpg" \
  -F "own_face_adult=true"

Follow, adjust and saveCopy Anchor Link

Poll GET /personas/{id} every 5 seconds until image_status is ready. POST /personas/{id}/regenerate tries again, with new chips or with a one-line note such as make the jacket red. When the photo is right, save it:

curl -X POST https://api.cut.pro/api/v1/personas/PERSONA_ID/save \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ana" }'

Ready-made charactersCopy Anchor Link

GET /personas/presets lists characters whose photo already exists, from weird ones to everyday creators. POST /personas/presets/{presetId} turns one into a persona free of charge, ready to name with POST /personas/{id}/save and use in videos. To star favorites: PUT /personas/presets/{presetId}/favorite with { "favorite": true }.

VersionsCopy Anchor Link

A saved persona can still be regenerated or edited with POST /personas/{id}/regenerate. Every photo that finishes becomes a new version and the current one; earlier ones stay in versions, on GET /personas/{id}. To go back to one, free of charge:

curl -X POST https://api.cut.pro/api/v1/personas/PERSONA_ID/versions/VERSION_ID/restore \
  -H "X-Api-Key: $CUTPRO_API_KEY"

Every video stays tied to the version it came from (version_id). New videos use the current version unless you send version_id to POST /personas/{id}/videos; GET /personas/{id}/videos?version_id=... lists only one version's videos. Videos already made do not change.

To tell us what worked, rate each photo with POST /personas/{id}/versions/{versionId}/feedback and each video with POST /personas/{id}/videos/{videoId}/feedback: { "vote": "up" }, or { "vote": "down", "reason": "..." } with the reason. Rating is free.

Upload the video and price itCopy Anchor Link

POST /personas/sources/upload returns a media_id and a signed URL. PUT the bytes there, call POST /personas/sources/upload/complete, then price the video. A video already in the library skips the upload.

quality picks the quality: standard (the default) follows the persona's traits and is the cheapest, up to 15 seconds in MP4; high also follows the persona's photos, keeps the face more faithful and takes up to 30 seconds, at a higher price. For a persona made from face photos, prefer high. replace says what changes in the video's main person: head changes only the head and hair and keeps the body and outfit, person (the default) replaces the whole person. Each quality's prices and limits are in GET /personas/catalog.

curl "https://api.cut.pro/api/v1/personas/swap/quote?media_id=MEDIA_ID&quality=standard&replace=head" \
  -H "X-Api-Key: $CUTPRO_API_KEY"

{ "media_id": "7412908365112823", "quality": "standard", "replace": "head", "seconds": 8.4, "credits": 81 }

Start the videoCopy Anchor Link

type is the kind of video, and swap is the one that exists today. Send the credits you got from the quote, with the same quality and replace. If the server measures a different price, it answers 409 PRICE_CHANGED with the right one in extra, and nothing is charged.

curl -X POST https://api.cut.pro/api/v1/personas/PERSONA_ID/videos \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "swap", "media_id": "7412908365112823", "quality": "standard", "replace": "head", "credits": 81 }'

Poll GET /personas/{id}/videos/{videoId} every 10 seconds. When status is ready, download_url has the MP4 and edit_id goes straight to POST /renders or POST /posts.