Avatar Face Swap API (Beta): apply an avatar face to a video

Avatar Face Swap 1.0 is a Beta model-run endpoint on the Sume API that applies a ready avatar's face onto a public source video. Send POST /v1/models/sume/avatar-face-swap/v1.0/runs with an avatar_handle, a video_url, and a quality tier. Sume creates a job-backed face-swap resource, and a completed resource exposes a public-safe video_url under media.sume.com.

Every detail below comes from the Face swap (Beta) docs page.

Is Avatar Face Swap still in Beta?

Yes. The docs mark Avatar Face Swap 1.0 as a Beta model-run endpoint and tie two rules to the Beta: quality is required, with no omit default, and worker validation is currently planned for source videos of about 4-15 seconds with usable audio.

When should I use Face Swap instead of an avatar video?

Use only the Developer API path above; it is not the old consumer-product /face-swap route. The docs point to Face Swap when:

• You already have a ready Avatar 1.0 identity. How to create a reusable AI avatar shows how to make one.
• You have a short public source video and want the avatar face applied to it.
• You do not need script-driven talking-video generation. For that, see Talking avatar video API.

How do I create a face-swap job?

Send the three required fields. In Beta, quality is required; there is no omit default on this endpoint.

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" \
  -d '{
    "avatar_handle": "product_host",
    "video_url": "https://example.com/inputs/source-video.mp4",
    "quality": "plus"
  }'

Which source videos does Face Swap accept?

Beta worker validation targets source videos suitable for face-swap processing, currently planned for about 4-15 seconds with usable audio. The video_url must be a fetchable public HTTPS video URL. These are rejected:

• Localhost URLs.
• Private-network URLs.
• Non-HTTPS URLs.
• Signed or private URLs.
• Provider task URLs.

What does Face Swap not do?

The docs list these as intentionally unsupported on this endpoint:

• Prompts and transcripts.
• Duration knobs and aspect ratio.
• Avatar ids in the body. Name the avatar with avatar_handle.
• Provider fields.

How do I get the result?

Poll the job status, then fetch the result. Completed resources expose a public-safe video_url and artifacts under media.sume.com when ready. Prefer resource_status for readiness and job_status for polling.

Face Swap takes the same communication modes as other generation submits, where documented in OpenAPI:

curl https://api.sume.com/v1/jobs/job_123/status \
  -H "Authorization: Bearer $SUME_API_KEY"

curl https://api.sume.com/v1/jobs/job_123/result \
  -H "Authorization: Bearer $SUME_API_KEY"

What does Face Swap cost?

Face Swap needs a ready avatar. Creating one is $0.95 per avatar, with the default 5.5% agent fee on top. The face-swap run is priced per quality tier; the current rates are in the public catalog, GET /v1/catalog.