Face swap a video with a photo: create an avatar first

To face swap a video with a photo, give a face-swap tool the photo as the new face and the video as the target, and it puts that face onto the person in the video. Sume's Avatar Face Swap (Beta) takes a ready avatar rather than a photo, so first turn the photo into an avatar with POST /v1/avatar-1.0/generate, then send the avatar's handle, a public source video of about 4–15 seconds with usable audio, and a quality tier to POST /v1/models/sume/avatar-face-swap/v1.0/runs.

Sume facts come from the Face swap (Beta) and Create new avatar docs and the avatar schemas in the Sume API reference, read on 2026-09-27. Anything called current behavior is read from Sume's code. Avatar Face Swap API (Beta) covers the swap endpoint on its own.

Can I send a photo straight to Sume's face swap?

No. The request has three required fields, avatar_handle, video_url, and quality, and no image field. The schema calls it a strict Beta contract: avatar ids, prompts, transcripts, duration, aspect ratio, and provider fields are intentionally unsupported. The face has to come from a ready avatar.

How do I turn the photo into an avatar?

Send the photo to POST /v1/avatar-1.0/generate with input.type: "photo" and a new avatar_handle, then poll the job until the avatar is ready:

• image_url must be a fetchable public HTTPS image. Localhost, private-network, non-HTTPS, and non-image responses are rejected before generation.
• Handles take letters, digits, underscores, and periods. Hyphens are not supported.
• Poll GET /v1/jobs/:id/status, then read the avatar with GET /v1/avatar-1.0/avatars/:id. Creating it costs $0.95 per avatar.

curl -X POST https://api.sume.com/v1/avatar-1.0/generate \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: avatar-from-photo-001" \
  -d '{
    "avatar_handle": "swap_face",
    "input": {
      "type": "photo",
      "image_url": "https://example.com/face.png"
    }
  }'

Will the swapped face look exactly like my photo?

Not exactly. Today Sume builds a photo avatar by generating a new portrait from your photo, prompted with "Photo of this person", so the face that goes onto the video is that generated likeness, not the pixels of your photo. Before you swap, open the avatar's preview_image_url, its representative Sume-hosted image, and check it.

How do I run the face swap?

Send the avatar's handle, the source video, and a tier. In Beta, quality is required (standard, plus, or max) and has no default, and the source should be a fetchable public HTTPS video of about 4–15 seconds with usable audio. When the job completes, the swapped video is a public-safe video_url under media.sume.com. Avatar Face Swap API (Beta) lists the URLs the endpoint rejects and how to poll the job.

curl -X POST https://api.sume.com/v1/models/sume/avatar-face-swap/v1.0/runs \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: face-swap-001" \
  -d '{
    "avatar_handle": "swap_face",
    "video_url": "https://example.com/inputs/source-video.mp4",
    "quality": "plus",
    "mode": "async"
  }'

What does it cost, and what are the limits?

You pay for the avatar once, at creation. For each swap, Sume today reserves the tier's no-product avatar-video rate for the 15-second Beta maximum, as GET /v1/catalog states and the table shows, and the catalog notes that final pricing may be refined before GA. Successful jobs capture the reservation; failed jobs release or refund it. Both are plus a 5.5% agent fee by default.

• Face Swap is Beta, and its source window is planned rather than final.
• The face is the avatar's generated likeness, and the request has no prompt, script, duration, or aspect ratio control.
• Use a photo and a video you have the rights and the subject's consent to use.