Job lifecycle
- Upload a photo. Send a clear portrait as a
referenceasset. - Pick a scene. Send the scene clip as a
sourceasset. If several people are visible, choose one actor with the faces endpoint. - Create a job. The service prepares the inputs and pauses for input review.
- Follow progress. Poll the job or its events. Accept the inputs to start generation. Then inspect the draft and accept or reject it.
- Get the result. Download the video after technical checks pass and you accept the draft.
Each review uses a fingerprint. An acceptance applies only to the exact version that you inspected.
Quickstart
Replace YOUR-HOST and the token with the values from your onboarding contact.
export HOST=https://YOUR-HOST
export TOKEN=your-bearer-token
# 1. Upload the portrait and the scene
curl -s -H "Authorization: Bearer $TOKEN" \
-F role=reference -F file=@portrait.jpg $HOST/v1/assets
curl -s -H "Authorization: Bearer $TOKEN" \
-F role=source -F file=@scene.mp4 $HOST/v1/assets
# 2. Optional: list faces in the scene and pick an actor
curl -s -H "Authorization: Bearer $TOKEN" $HOST/v1/assets/SCENE_ID/faces
# 3. Create the job
curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: scene-1-portrait-1" \
-d '{"source_asset_id":"SCENE_ID","reference_asset_id":"PORTRAIT_ID",
"target":{"face_index":0},"authorization":{"accepted":true}}' \
$HOST/v1/jobs
# 4. Follow progress
curl -s -H "Authorization: Bearer $TOKEN" "$HOST/v1/jobs/JOB_ID/events?after=0"
curl -s -H "Authorization: Bearer $TOKEN" $HOST/v1/jobs/JOB_ID
# 5. Review: once for the inputs, once for the draft
curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"decision":"accept","fingerprint":"FINGERPRINT"}' \
$HOST/v1/jobs/JOB_ID/review
# 6. Download the result
curl -s -H "Authorization: Bearer $TOKEN" -o result.mp4 \
$HOST/v1/jobs/JOB_ID/resultTake FINGERPRINT from action_required.fingerprint in the job status. Some accounts need extra job fields. Your onboarding contact gives them to you.
Limits
- Scene video. MP4, MOV or WebM. 4 to 30 seconds, with one soundtrack.
- Portrait. JPEG, PNG or WebP. At least 64 pixels per side, with a visible face.
- One actor per job. The scene can show several people. The service replaces one selected face.
- Output. A draft video at 24 FPS, up to 960 pixels on the long edge, with the original soundtrack.
- Not supported. Hair, body, clothing or object replacement, masks, strength controls and seeds.
- Live limits.
GET /v1/capabilitiesreturns the exact limits of your deployment.