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 endpoint 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 you want to apply the avatar face to that video.
  • You do not need script-driven talking-video generation. For that task, use Avatar videos.

Create a face-swap job

The required fields are avatar_handle, video_url, and quality.

In Beta, quality is a required field (standard | plus | max). If you omit the field, this endpoint does not use a default value.

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.
  • The endpoint rejects localhost, private-network, non-HTTPS, signed/private URLs, and provider task URLs.
  • In Beta, the worker validation is for source videos that are applicable to the face-swap process. The current plan is approximately 4-15 seconds with usable audio.
  • By design, the endpoint does not support prompts, transcripts, duration knobs, aspect ratio, avatar ids in the body, or provider fields.

Poll and recover

When a completed resource is ready, it exposes a public-safe video_url / artifacts under media.sume.com. Use resource_status as the primary signal for readiness. Use job_status when you poll.

Communication modes

This endpoint has the same options as other generation submits that OpenAPI documents: async (default-style immediate return), sync / subscribe with wait_timeout_seconds, and webhook with a public HTTPS webhook_url.