Media tools
Face swap (Beta)
Beta Avatar Face Swap — apply a ready avatar face onto a public source video.
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.
POST /v1/models/sume/avatar-face-swap/v1.0/runsThis 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.
curl -sS -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: $(uuidgen)" \
-d '{"avatar_handle":"sume_clawra","video_url":"https://example.com/inputs/source-video.mp4","quality":"plus","mode":"async"}'Hard constraints
video_urlmust 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
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"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.