Face swap (Beta)

Avatar Face Swap 1.0 is a Beta model-run endpoint. It creates a job-backed face-swap resource from a ready avatar handle and a public HTTPS source video.

This is not the old consumer-product /face-swap route. Use only the Developer API path above.

When to use

  • You already have a ready Avatar 1.0 identity.
  • You have a short public source video and want the avatar face applied to it.
  • You do not need script-driven talking-video generation (use Avatar videos for that).

Create a face-swap job

Required fields: avatar_handle, video_url, and quality.

quality is required in Beta (standard | plus | max). There is no omit default on this endpoint.

Create a face-swap job (Beta)

POST /v1/models/sume/avatar-face-swap/v1.0/runs

Required

Hard constraints

  • video_url must be a fetchable public HTTPS video URL.
  • Localhost, private-network, non-HTTPS, signed/private URLs, and provider task URLs are rejected.
  • Beta worker validation targets source videos suitable for face-swap processing — currently planned for about 4-15 seconds with usable audio.
  • Prompts, transcripts, duration knobs, aspect ratio, avatar ids in the body, and provider fields are intentionally unsupported.

Poll and recover

Completed resources expose a public-safe video_url / artifacts under media.sume.com when ready. Prefer resource_status for readiness and job_status for polling.

Communication modes

Same options as other generation submits where documented in OpenAPI: async (default-style immediate return), sync / subscribe with wait_timeout_seconds, and webhook with a public HTTPS webhook_url.