Create personas and swap the person in the video

Read the catalogCopy Anchor Link

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 response is 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"
    }
  }'

With the face of whoever uses it. Upload the photos first and pass the ids in face_ids, within 24 hours and up to max_face_photos (6). JPEG, PNG, WebP or HEIC up to 10 MB. own_face_adult: true confirms the photo is of whoever uses it and that this person is 18 or older.

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"

With face_ids, only the traits in face_photo_groups still apply, and for those the photo option keeps the feature as it is in the photos.

From a ready-made character, for free. GET /personas/presets lists characters with the photo already made (category: weird, cartoon, creator or influencers). Creating from one generates nothing and is born with image_status: ready:

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

With name, the persona comes out already saved. Without name, it is a draft to save later. It remains that character: on a regenerate, the chips are ignored and only the note edits. PUT /personas/presets/{presetId}/favorite with { "favorite": true } marks favorites.

Adjust and saveCopy Anchor Link

Poll GET /personas/{id} every 5 seconds until image_status becomes ready, or failed with the reason in error_code.

To change the photo, generate again with other chips or edit with a one-line note, which keeps the same person:

curl -X POST https://api.cut.pro/api/v1/personas/$PERSONA_ID/regenerate \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "make the jacket red" }'

An edit with note costs pricing.photo_with_references_credits. If another photo is already being generated, the response is 409 CARD_LOCKED.

When the photo is good, save it. On a saved persona, the same call only renames 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" }'

Upload the source videoCopy Anchor Link

A video that is already in the library skips this step: use its id as media_id. For a new file, request the URL, upload and confirm. MP4 and MOV only, within video_limits.

curl -X POST https://api.cut.pro/api/v1/personas/sources/upload \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "video.mp4", "file_size": 8421337, "content_type": "video/mp4" }'

curl -X PUT "$UPLOAD_URL" -H "Content-Type: video/mp4" --upload-file video.mp4

curl -X POST https://api.cut.pro/api/v1/personas/sources/upload/complete \
  -H "X-Api-Key: $CUTPRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "media_id": "7412908365112823", "file_name": "video.mp4" }'

Ask for the priceCopy Anchor Link

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

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

Nothing is charged. Show the price to the person and wait for a yes.

The price depends only on quality, duration and style. head and person cost the same. A video refused in standard may fit in high.

Generate the videoCopy Anchor Link

Send the price's credits, with the same quality, replace and style. The response is 202 with status: processing.

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 }'

If the price changed, nothing is charged and the response is 409 PRICE_CHANGED with the right value in extra.credits.

By default, whoever becomes the persona is the main person in the video. To choose another, send target:

• a person seen in the video: { "seconds": 2.5, "x": 0.62, "y": 0.48 }, with the moment and their center from 0 to 1. box is optional and helps when there are people nearby.
• whoever is filming: { "camera": true }.

Choosing the person never raises the confirmed price. If nobody is at that point, the video ends in failed with TARGET_NOT_A_PERSON and the credits come back.

Poll GET /personas/{id}/videos/{videoId} every 10 seconds.

• ready: download_url has the MP4, valid for 6 hours. To post or render, POST /generations/{videoId}/edit returns the edit_id that goes in POST /posts or POST /renders.
• failed: the reason is in error_code and the credits have already come back.