Video Head Swap API: 분석, 대상 선택, 편집

Video Head Swap은 두 단계 API 작업 흐름입니다. 5~30초 MP4를 분석하고 번호가 붙은 머리 미리보기를 확인한 다음, 고른 위치와 교체용 사진을 편집에 보냅니다. 얼굴, 헤어스타일, 머리 색, 머리 모양은 바뀝니다. 몸, 의상, 동작, 음성, 그리고 선택하지 않은 다른 사람들은 모두 그대로 남습니다.

여기서는 편집 요금을 내기 전에 먼저 추적된 머리를 모두 보고 원하는 것을 지정합니다. 이미 있는 영상을 편집하는 기능입니다. 두 장의 스틸 사진을 연기처럼 움직이게 하지 않습니다. 그런 용도에는 이미지에서 영상으로 가는 모델을 쓰세요.

알맞은 교체를 고르기

원본의 머리카락을 그대로 둘 수 있다면 얼굴 교체 쪽이 더 싸고 간단합니다. 머리 교체는 새 머리카락이 캐릭터의 일부일 때 값을 합니다. 대신 목 부분의 이음새가 생겨 직접 확인해야 합니다.

소스와 참조 사진 준비하기

처리할 권한이 있는 얼굴만 사용하세요. 본인, 서명한 동의서가 있는 출연자, 또는 만들어진 머리 중 하나입니다. 화면에 나오는 사람은 모두 성인이어야 합니다. 두 호출 모두 무검열이므로 SpicyAPI는 내용 필터를 넣지 않으며, 그 확인은 이용자 몫입니다.

이 예에서는 녹슨 색 재킷을 입은 가상의 성인이 12초짜리 대화 도중 다른 성인을 향해 돌아섭니다. 첫 번째 사람의 머리만 교체하고, 두 번째 사람과 의상, 대사는 그대로 두세요.

분석하기 전에 최종 소스를 내보내세요. MP4, 최대 90 MB, 5~30초입니다. video_url에는 MP4 자체를 돌려주는 공개 HTTPS 링크(HTML 플레이어 페이지가 아님)를 넣거나, 무료 업로드 절차에서 나온 spicy:// URI를 넣습니다. 로컬 파일이라면 이 방법이 가장 확실합니다. 나중에 소스를 자르거나 크기를 바꾸거나 다시 인코딩하면 분석을 다시 실행하세요.

같은 교체용 성인의 사진을 1~3장 준비하세요. 정면과 3/4면은 출발점으로 쓸 만한 조합입니다. 소스에 큰 머리 회전이 들어 있으면 프로필 사진을 추가하세요. 한 세트 안에서 머리카락과 겉보기 나이가 어긋나지 않게 유지하세요. 영상과도 맞춰 주세요. 사진은 장면이 빛을 받는 방향에서 비추고, 머리도 비슷한 각도로 두세요. 어긋남은 목의 이음새에서 드러나고, 요청 항목 중 어떤 것으로도 이를 보정할 수 없습니다. 전신 의상 참조는 인물 교체에 속합니다. 이 작업에는 의도한 머리와 머리카락이 또렷하게 보여야 합니다.

가상의 참조 이미지에는 아래와 같은 브리핑을 쓰세요.

가상의 성인 남성 한 명, 35세쯤, 짧은 어두운 머리카락, 정돈된 수염, 무표정. 단추를 모두 잠근 무지 셔츠를 입고 있다. 부드럽고 균일한 조명, 가리지 않은 얼굴과 머리, 단순한 배경. 정면, 다른 사람 없음, 글자 없음.

다른 각도는 승인한 그 동일 인물에서 만드세요. 서로 관계없는 사람을 각각 따로 요청하지 마세요. 편집에는 prompt 항목이 없으므로, 참조 사진이 결과 전체를 결정합니다.

정면, 3/4면, 프로필로 이루어진 참조 세트의 삽화.

먼저 Playground에서 해보기

1. Video Head Swap 편집 페이지를 열고 Playground 탭의 Form 뷰에 그대로 머무릅니다. 실행하려면 잔액이 있는 계정으로 로그인하세요.
2. 1단계, Find the people in your clip. Input video에 클립을 넣고(MP4를 놓거나 Asset URL 사용), Resolution에서 480p 또는 720p를 고릅니다. 편집도 같은 값을 써야 하므로, 완성 클립에 원하는 해상도를 고르세요. Find people in this clip을 누릅니다($0.08).
3. 2단계, Choose who to replace. 추적된 머리마다 번호가 붙은 미리보기가 나타납니다. 원하는 것을 고르고 교체용 성인의 참조 사진을 한 장에서 세 장까지 추가하세요. Seed는 참조 세트를 공정하게 비교하고 싶을 때만 지정하고, 그 외에는 빼세요.
4. 편집을 실행한 뒤 소리를 켠 상태로 결과의 턱, 목, 머리카락, 옷깃을 확인하세요.

분석 결과는 24시간 동안 다시 쓸 수 있습니다. 같은 미리보기에서 다른 참조 세트를 더 해 볼 수 있고, 추적 비용을 다시 내지 않아도 됩니다. 승인된 편집은 참조 세트나 시드를 새로 쓰더라도 새로운 유료 작업입니다. 어느 미리보기에도 원하는 사람이 나오지 않는다면 더 선명한 컷이 답입니다. 한 번도 또렷하게 보이지 않는 머리는 추적할 수 없고, 추적할 머리가 없는 클립은 실패하면서 예약 금액이 해제됩니다.

분석 페이지는 1단계만 단독으로 실행합니다. 분석이 성공하면 거기서 멈춰도 요금이 붙습니다.

그다음 코드로 실행하기

Python SDK(pip install spicyapi)를 설치하고, 환경에 SPICY_API_KEY를 설정한 다음 이 코드를 swap.py로 저장하세요. analyze는 미리보기 URL을 출력하고, edit는 분석 작업 ID와 선택한 미리보기 위치를 받습니다. 편집은 분석과 같은 API 키와 같은 해상도를 써야 하며, video_url은 받지 않습니다. 분석된 클립을 그대로 물려받습니다.

import sys
import uuid
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

def run(model: str, input_data: dict) -> tuple[str, list]:
    task = client.create_task(model=model, input_data=input_data,
                              idempotency_key=str(uuid.uuid4()))
    final = client.wait_for_terminal(task["taskId"])
    if final["state"] != "succeeded":
        raise RuntimeError(f"{task['taskId']} ended as {final['state']}: {final.get('errorCode')}")
    return task["taskId"], output_assets(final)

if sys.argv[1] == "analyze":
    task_id, previews = run("spicyapi/head-swap-video-v1/video-analyze", {
        "video_url": "https://your-media.example/conversation.mp4",
        "resolution": "720p",
    })
    print("analysis task:", task_id)
    for position, asset in enumerate(previews):   # position 0 is the first image returned
        print(position, asset["url"])
else:  # python swap.py edit <analysis_task_id> <position>
    _, outputs = run("spicyapi/head-swap-video-v1/video-edit", {
        "analysis_task_id": sys.argv[2],
        "resolution": "720p",
        "swap_targets": [{
            "object_index": int(sys.argv[3]),
            "image_urls": [
                "https://your-media.example/replacement-front.png",
                "https://your-media.example/replacement-three-quarter.png",
            ],
        }],
        "seed": 42,
    })
    print(outputs[0]["url"])  # copy the video to your own storage now

python swap.py analyze를 실행하고, 모든 미리보기를 열어 원하는 성인의 번호를 적어 두세요(위치 0은 첫 번째로 반환된 이미지이며, 왼쪽에서 오른쪽으로 세는 규칙이 아닙니다. 원하는 사람이 없는데 0으로 되돌아가지 마세요). 그다음 python swap.py edit <analysis_task_id> 1을 실행합니다. 편집은 대상 1개에서 10개를 받고, 각 대상마다 같은 사람의 참조 이미지를 1~3장 받습니다. 마스크, 의상, 음성, 프롬프트 입력은 없습니다. 생성, 대기, 재시도, 멱등 키, 다운로드는 작업 안내와 Python SDK 레퍼런스에 다룹니다. 로컬 파일은 무료 업로드 절차를 거쳐 video_url에 쓸 spicy:// URI로 돌아옵니다.

또는 Agent에게 맡기기

어시스턴트가 두 호출을 실행하게 할 때, 세 가지 공식 도구 모두 가격을 보여 주고 유료 호출 전에 확인을 요청합니다.

• CLI. 분석의 input 객체(video_url, resolution)를 analysis.json에 넣고 다음을 실행하세요.

``bash spicyapi tasks create --model spicyapi/head-swap-video-v1/video-analyze --input-file analysis.json --wait ``

편집도 edit.json으로 같은 방식으로 실행합니다. CLI 문서를 참고하세요. npx @spicyapi/cli는 설치 없이 동작합니다.

• MCP 서버. MCP 서버를 추가하고 이렇게 물어보세요: "Analyse conversation.mp4 with Video Head Swap at 720p and show me the numbered previews." 파일을 spicyapi_upload_file로 올리고, 가격 확인을 위해 멈추는 spicyapi_task_create를 호출한 뒤 spicyapi_task_wait를 호출합니다. 위치는 직접 고른 다음 편집을 요청하세요.
• Skill. npx skills add spicyapi-ai/spicy-skill는 Agent Skill을 설치합니다. 덕분에 코딩 어시스턴트가 항목 이름을 추측하지 않고 실제 모델 스키마를 읽습니다.

완성된 편집은 어떤 모습인가

아래에 있는 공개 모델 예는 10초짜리 소스 클립과 참조 사진 한 장을 사용한 480p 편집입니다. 머리카락과 얼굴은 바뀌고, 드레스, 걸음, 역광, 카메라는 그대로입니다. 빛이나 각도가 어긋나는 지점인 턱과 목선을 먼저 확인하세요.

비용

편집은 480p에서 청구 초당 $0.064, 720p에서 $0.12입니다. 과금은 5초 단위 블록으로 진행되며, 5초가 최소, 30초가 상한입니다. 480p의 10초 클립은 총 $0.72로, 분석 $0.08에 편집 $0.64를 더한 값입니다.

정산 전에 편집은 30초 최댓값, 즉 480p에서 $1.92 또는 720p에서 $3.60을 예약합니다. 720p의 12초 클립은 편집 요금이 $1.80인데도 $3.60이 예약됩니다. 나머지는 작업이 정산될 때 해제됩니다.

선택, 동일성, 전달을 따로 진단하기

머리카락과 옷깃, 앞쪽 손을 확인하는 삽화.

반환된 영상을 소리와 함께 재생하세요. 편집은 소스의 음성과 몸 움직임을 유지합니다. 화자의 목소리는 바꾸지 않으며, 배경이 픽셀 단위로 완전히 같다는 보장은 없습니다. 선택하지 않은 사람도 검사하세요, 특히 서로 지나가는 구간에서요. 손이 교체된 얼굴을 가로지른다면, 보기 좋은 첫 프레임만 승인하지 말고 접촉과 다시 나타나는 순간을 프레임별로 확인하세요.

승인한 영상은 곧바로 자신의 저장소에 보관하세요. 결과 링크는 약 20분 동안만 유지되고 결과는 최대 14일 동안 보관되므로, 분석 ID와 미리보기 이미지, 임시 미디어 URL은 영구 사본이 아닙니다.