---
title: 페이스 스왑 (Beta)
description: Beta Avatar Face Swap — 준비된 아바타 얼굴을 공개 소스 비디오에 입히는 방법을 살펴보세요.
---

Avatar Face Swap 1.0은 **Beta** model-run 엔드포인트입니다. 준비된 아바타
handle과 공개 HTTPS 소스 비디오로 Job 기반 페이스 스왑 리소스를 만듭니다.

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

예전 소비자 제품의 `/face-swap` 라우트가 아닙니다. 위 Developer API 경로만
사용하세요.

## 언제 사용하나요

- 이미 준비된 Avatar 1.0 아이덴티티가 있습니다.
- 짧은 공개 소스 비디오가 있고 거기에 아바타 얼굴을 입히고 싶습니다.
- 스크립트 기반 말하는 비디오 생성은 **필요하지 않습니다**(그럴 때는
  [아바타 비디오](/models/avatar-videos)를 사용하세요).

## 페이스 스왑 Job 만들기

필수 필드는 `avatar_handle`, `video_url`, `quality`입니다.

Beta에서 `quality`는 필수입니다(`standard` | `plus` | `max`). 이 엔드포인트에는
생략 시 기본값이 없습니다.

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

### 반드시 지켜야 할 제약

- `video_url`은 가져올 수 있는 공개 HTTPS 비디오 URL이어야 합니다.
- localhost, 사설 네트워크, HTTPS가 아닌 URL, 서명된·비공개 URL, 프로바이더 작업
  URL은 거부됩니다.
- Beta 워커 검증은 페이스 스왑 처리에 적합한 소스 비디오를 대상으로 합니다.
  현재는 사용할 만한 오디오가 있는 **4~15초** 정도를 계획하고 있습니다.
- 프롬프트, 트랜스크립트, 길이 조절 값, 화면 비율, 본문 내 아바타 id, 프로바이더
  필드는 의도적으로 지원하지 않습니다.

## 폴링과 복구

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

완료된 리소스는 준비되면 `media.sume.com` 아래의 공개 가능한 `video_url`과
산출물을 노출합니다. 준비 여부는 `resource_status`로, 폴링은 `job_status`로
확인하세요.

## 통신 모드

OpenAPI에 문서화된 다른 생성 제출과 같은 옵션입니다. `async`(즉시 반환하는 기본
방식), `wait_timeout_seconds`와 함께 쓰는 `sync` / `subscribe`, 그리고 공개
HTTPS `webhook_url`을 쓰는 `webhook`입니다.

## 관련 문서

- [아바타 만들기](/models/avatar)
- [아바타 비디오 생성](/models/avatar-videos)
- [미디어 입력](/workflows/asset-library)
- [Job과 결과](/workflows/jobs-and-results)