Avatar face swap beta limits: 4 to 15 seconds, quality required

Sume Avatar Face Swap 1.0 is a Beta endpoint that applies a ready avatar face onto a public HTTPS source video. The source clip should run roughly 4 to 15 seconds and have usable audio, quality is a required field with no default, and the endpoint does not take prompts, transcripts, duration knobs or aspect ratio.

The request

Per Face swap (Beta), read 2026-10-08, the route is POST /v1/models/sume/avatar-face-swap/v1.0/runs. It is not the old consumer /face-swap route.

What it rejects

The endpoint rejects localhost, private-network and non-HTTPS URLs, signed or private URLs, and provider task URLs. By design it does not support prompts, transcripts, duration knobs, aspect ratio, avatar ids in the body or provider fields.

• Source length: approximately 4-15 seconds.
• Audio: the clip needs usable audio.
• Visibility: the URL must be reachable without a signature.
• Fields: only avatar_handle, video_url and quality.

Face swap or talking video?

Choose face swap when a real clip already exists and you want the avatar's face on it. Choose Avatar video when you only have a script and want Sume to generate the whole clip. If your source is longer than 15 seconds, face swap is not the right route; the related post on a 20-second person swap covers that case.

Completion works like other generation jobs. The default mode is async, sync or subscribe waits up to the documented bound, and webhook takes a public HTTPS webhook_url. When a completed resource is ready, use resource_status as the primary readiness signal and job_status when you poll.

Checking a source clip before you submit

Trim the clip to the supported length first, and confirm that it has audible speech. Host it on a public HTTPS URL that does not expire mid-job. Avoid signed links, because the endpoint rejects them by design.

Because quality has no default in Beta, a missing field is an error rather than an assumed tier. Pick standard for a quick check, plus for balanced results, and max when quality matters most, and send it explicitly every time.

As a Beta, the contract may change. Read the live OpenAPI at the Sume API reference before you build a pipeline around it, and keep your own tests so you notice a change early.