Video Character Swap: 레퍼런스, 대상 선택, 확인 작업

Character Swap는 장면, 카메라 이동, 원래 오디오는 그대로 두고 사람의 외관을 체형과 의상까지 통째로 바꾸고 싶을 때 씁니다. Character Swap는 클립 안에서 누구를 바꿀지 고를 수 있습니다. 최종 클립을 분석하고 번호가 붙은 미리보기를 확인한 다음, 고른 미리보기 번호와 교체할 사람의 이미지 1~3장을 제출합니다. 기존 의상을 그대로 유지해야 한다면 대신 head swap이나 face swap 워크플로를 쓰세요.

SpicyAPI에서 분석과 편집은 별도로 과금되는 작업입니다. 7초 소스는 전체로 480p 기준 $0.72, 720p 기준 $1.28입니다. 분석 한 번에 10초로 올림된 편집을 더한 값입니다. Playground는 두 단계를 브라우저에서 실행하고 API는 같은 입력을 받습니다. 영상과 레퍼런스 이미지에 나온 사람의 초상(닮은 모습)에 대해 모두 사용 허가가 필요합니다.

7초 장면과 전신 교체 준비하기

예는 누군가 닫힌 공구함을 들고 작업대로 가져가는 7초 장면이며, 다른 성인이 그 옆에 서 있습니다. 공구함을 든 쪽은 네이비 작업 재킷과 차콜 회색 바지를 입은 가상의 성인으로 교체됩니다. 아래 일러스트가 그 모습입니다. 작업대, 공구함, 다른 사람, 원래 연기는 그대로 유지됩니다.

편집할 7초 소스를 그대로 내보내세요. 처음 잡는 동작, 운반 동작, 공구함이 작업대에 닿은 뒤의 놓는 동작을 그대로 남기세요. 입력은 최대 90 MB까지 5~30초짜리 MP4입니다. 파일을 업로드하는 경로가 가장 확실하며, 직접 링크는 MP4 파일 자체를 가리켜야 합니다. 플레이어가 있는 페이지는 실패합니다(요금은 환불됩니다). 분석 후 자르거나 다시 인코딩하면 분석을 새로 해야 합니다.

트래커는 어느 정도 크고 보이는 사람을 따라가므로, 필요한 구간만 잘라내고 목표인 사람이 완전히 가려진 상태가 길게 이어지는 구간은 피하세요. 편집은 5초 단위로 과금되므로 짧은 컷이 더 저렴합니다.

교체할 쪽으로는 같은 성인의 전신 정면 뷰와 3/4 뷰를 같은 복장으로 준비하세요. 선명한 레퍼런스는 한 장만 있어도 되고, 대상당 최대 세 장입니다. 머리와 어깨만 나온 초상화는 체형과 의상을 추측하게 되므로 소매, 손, 신발을 보여주고, 가장 선명한 초상화 하나를 고르기보다 레퍼런스도 촬영물과 같은 조명으로 맞추세요. 한 장에는 A의 얼굴, 다른 장에는 B의 바지, 세 번째 장에는 또 다른 재킷을 담는 식으로 섞지 마세요. 서비스는 이를 각각의 의상 레이어가 아니라 한 번의 교체에 대한 레퍼런스로 받습니다.

이미지 생성에 쓸 수 있는 브리프는 다음과 같습니다.

가상의 성인 여성, 약 30세, 전신 레퍼런스 초상화. 무늬 없는 네이비 작업 재킷, 차콜 회색 바지, 어두운 플랫슈즈. 정면을 향한 편안한 자세, 손이 보이도록, 소매와 신발이 명확하게, 중립 배경. 공구함 없음, 다른 사람 없음, 글자 없음.

필요하면 확정한 같은 디자인의 두 번째 각도를 생성하거나 촬영하세요. character swap 편집에는 텍스트 프롬프트 필드도, 의상 선택기도, 신체 마스크도 없습니다. 그래서 원하는 의상은 레퍼런스 이미지에 들어 있어야 합니다.

정면과 3/4 각도의 전신 레퍼런스 세트 일러스트.

먼저 Playground에서 해보기

1. Video Character Swap 모델 페이지를 열고 Playground 탭의 Form 뷰를 그대로 사용하세요. 실행하려면 잔액이 있는 계정으로 로그인합니다.
2. Step 1, Find the people in your clip에서 7초짜리 MP4를 Input video에 넣고(업로드는 링크보다 확실합니다), 완성 클립에 필요한 Resolution인 480p 또는 720p를 고르세요. 편집도 같은 값을 써야 합니다.
3. Find people in this clip을 누릅니다($0.08). 찾은 모든 사람이 Step 2, Choose who to replace에 한 사람당 한 장의 잘라낸 미리보기로 나타납니다.
4. 공구함을 든 사람의 미리보기를 고르고, 교체할 사람의 레퍼런스 이미지를 1~3장 추가한 뒤 편집을 실행하세요. Seed는 선택 사항입니다.

위치 0이 첫 번째로 반환된 미리보기입니다. 순서는 화면상의 위치가 아니라 추적에서 오기 때문에 반드시 가장 왼쪽이나 가장 큰 사람이라는 뜻은 아닙니다. 공구함을 든 사람이 두 번째 미리보기라면 그 인덱스는 1입니다. 미리보기를 저장할 때는 반환된 순서를 유지하세요. 알파벳순 파일명이나 정렬된 갤러리가 인덱스를 조용히 바꿀 수 있습니다.

목표인 사람에게 미리보기가 없다면, 가까운 번호를 추측해서 편집 비용을 내지 마세요. 레퍼런스 이미지로 미리보기 없는 사람을 되살릴 수는 없습니다. 대신 그 사람이 또렷하게 보이는 테이크를 쓰세요. 아무도 찾지 못한 분석은 실패로 끝나고 예약이 해제됩니다. 분석이 성공했다면 교체하지 않기로 결정해도 과금됩니다.

그다음 코드로 호출하기

Python SDK(pip install spicyapi)를 설치하고 SPICY_API_KEY를 설정한 뒤 다음을 실행하세요. 클립과 레퍼런스 두 장을 업로드하고, 분석을 실행하고, 미리보기 링크를 출력하고, 어떤 인덱스를 바꿀지 물은 뒤 편집을 제출합니다. 두 작업 모두 과금됩니다.

import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
RESOLUTION = "720p"     # must be identical in both calls

clip = client.upload_file("./workshop-seven-seconds.mp4")
front = client.upload_file("./replacement-front.png")
angled = client.upload_file("./replacement-three-quarter.png")

analysis_task = client.create_task(
    model="spicyapi/character-swap-v1/video-analyze",
    input_data={"video_url": clip["uri"], "resolution": RESOLUTION},
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume analysis:", analysis_task["taskId"], flush=True)
analysis = client.wait_for_terminal(analysis_task["taskId"])
if analysis["state"] != "succeeded":
    raise RuntimeError(f"Analysis {analysis_task['taskId']} ended as {analysis['state']}")

previews = output_assets(analysis)
if not previews or any(p.get("pending") or p.get("unavailable") or not p.get("url") for p in previews):
    raise RuntimeError(f"Analysis {analysis_task['taskId']} has no ready previews; retrieve it before editing")
for index, preview in enumerate(previews):  # keep the returned order
    print(index, preview["url"])
chosen = int(input("Index of the person to replace: "))
if not 0 <= chosen < len(previews):
    raise ValueError("Choose one of the returned preview indices before creating an edit")

edit_task = client.create_task(
    model="spicyapi/character-swap-v1/video-edit",
    input_data={
        "analysis_task_id": analysis["taskId"],  # video_url is inherited from the analysis
        "resolution": RESOLUTION,
        "swap_targets": [{"object_index": chosen,
                          "image_urls": [front["uri"], angled["uri"]]}],
        "seed": 42,
    },
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)
print("Resume edit:", edit_task["taskId"], flush=True)
edit = client.wait_for_terminal(edit_task["taskId"])
if edit["state"] != "succeeded":
    raise RuntimeError(f"Edit {edit_task['taskId']} ended as {edit['state']}")
assets = output_assets(edit)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {edit_task['taskId']} has no ready output; check this task before a new run")
print(assets[0]["url"])  # copy it to your own storage now

업로드, 대기, 오류, 재시도는 subject swap 가이드, 작업 문서, Python SDK 레퍼런스에 정리되어 있습니다. 두 단계에 같은 API 키를 쓰고, 편집은 분석 후 24시간 이내에 실행하세요(업로드한 클립도 하루 뒤에 만료됩니다). 분석 한 번으로 각각 과금되는 편집을 여러 번 돌릴 수 있습니다. 목록에 넣지 않은 사람은 그대로 남고, 인덱스는 이 분석에 속하므로 다른 촬영에서 캐릭터 ID로 재사용하지 마세요.

전신 교체는 장면, 카메라 이동, 안무, 원래 오디오를 유지할 것을 전제로 합니다. 이 범위는 배경 픽셀이 변하지 않거나 새로운 목소리가 나온다고 약속하지 않습니다.

또는 Agent에게 맡기기

어시스턴트가 교체를 실행하게 하려면 CLI나 MCP 서버를 넘기세요. 둘 다 가격을 보여주고 유료 호출 전에 확인을 요청합니다. Skill은 그 위에 지시를 덧붙입니다.

• CLI. spicyapi는 터미널에서 작업 하나를 실행합니다(npx @spicyapi/cli는 설치 없이도 동작합니다):

``bash spicyapi files upload ./workshop-seven-seconds.mp4 # prints a spicy:// URI spicyapi tasks create --model spicyapi/character-swap-v1/video-analyze \ --input-file analysis.json --idempotency-key workshop-analysis-v1 --wait ``

analysis.json에는 {"video_url": "spicy://...", "resolution": "720p"}를 담습니다. 미리보기를 본 다음 video-edit와 자체 키 workshop-edit-v1, 그리고 analysis_task_id, resolution, swap_targets를 담은 input.json으로 명령을 실행하세요. 키는 요청 내용이 바뀌지 않았을 때만 다시 씁니다. 새 소스, 새 대상, 새 레퍼런스 묶음에는 새 키가 필요합니다.

• MCP 서버. MCP 서버(설정 스니펫은 그 페이지에 있습니다)를 어시스턴트에 추가한 다음 이렇게 물어보세요. "Character Swap로 ./workshop-seven-seconds.mp4를 720p에서 분석하고 미리보기를 보여줘." 사람을 고른 뒤에는 "인덱스 1을 ./replacement-front.png과 ./replacement-three-quarter.png로 교체해"라고 말하세요. spicyapi_upload_file을 호출하고, 이어서 spicyapi_task_create(가격 확인을 위해 멈춥니다)를 호출한 뒤 spicyapi_task_wait을 호출합니다.
• Skill. npx skills add spicyapi-ai/spicy-skill은 Agent Skill을 설치합니다. 코딩 어시스턴트가 현재 스키마를 읽고 멱등 키를 재사용하도록 알려줍니다. Skill 자체는 작업을 실행하지 못하므로 CLI나 MCP와 함께 쓰세요. 어떤 미리보기를 바꿀지는 여전히 사람이 결정합니다.

변형을 만들기 전에 과금 구조 파악하기

가격은 공개 카탈로그 기준(2026년 10월)입니다.

편집 길이는 5초 단위 블록으로 올림하고, 최솟값은 5초, 상한은 30초입니다. 5초 소스는 블록 하나를 쓰고, 5.1초는 블록 두 개를 씁니다. 제출 전에 편집 견적은 30초 최댓값을 예약하며, 480p 기준 $1.92, 720p 기준 $3.60이고, 작업이 정산되면 차이가 반환됩니다. 따라서 예산 확인은 예상 최종 금액뿐 아니라 예약분도 확보해야 합니다. 생성 단계에서 거부된 요청(해상도 불일치, 잘못된 분석 ID, 인덱스 중복)은 아무것도 만들지도 과금하지도 않습니다.

분석 하나를 재사용한 7초 소스의 720p 편집 두 번은 총 $2.48입니다. $0.08에 $1.20 두 배를 더한 값입니다. 레퍼런스나 seed를 바꾸면 새 유료 편집이며, 무료 수정이 아닙니다.

올바른 문제 고치기

인화한 프레임을 확인하는 일러스트.

공구함을 든 사람, 공구함, 선택되지 않은 성인 셋을 보통 속도로 함께 보세요. 그다음 잡는 동작, 작업대 접촉, 놓는 동작을 확인합니다. 가운데 행동이 실패해도 새 얼굴은 훌륭해 보일 수 있습니다. 마지막 0.5초에만 결함이 있다면 자르는 것으로 충분할 수 있습니다. 잡는 동작이 내내 깨져 있다면 더 또렷한 소스를 고르거나, 원래 몸과 의상을 남길 수 있다면 범위가 더 좁은 head 교체 방식을 쓰세요.

승인한 클립은 만료되기 전에 자신의 저장소로 복사하세요. 결과는 약 14일 동안 보관됩니다(미디어 보관 및 전달 참고).