---
title: Face swap (Beta)
description: 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.

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

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](/models/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.

<!-- api-call-example:face-swap-run -->

### 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

```bash
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"
```

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`.

## Related

- [Create new avatar](/models/avatar)
- [Generate avatar video](/models/avatar-videos)
- [Media inputs](/workflows/asset-library)
- [Jobs and results](/workflows/jobs-and-results)