AI 얼굴 교체 API 워크플로: 승인된 업로드, 비동기 작업, 안정적인 전달

교환 전에 레퍼런스 사진과 색을 비교한다.

SpicyAPI의 Face Swap은 이미지 2장(또는 이미지 1장과 클립 1개)만 받는, 프롬프트도 마스크도 필요 없는 규제 없는 엔드포인트 모음입니다. 이 가이드는 어떤 엔드포인트를 호출할지, 먼저 Playground에서 어떻게 시험하고 코드나 에이전트로 어떻게 호출할지, 무엇을 확인해야 하는지, 플랫폼이 삭제한 뒤에도 결과를 어떻게 보관하는지를 설명합니다.

작업에 맞는 엔드포인트 고르기

먼저 $0.013인 Face Swap부터 시작하세요. 교환한 얼굴이 화면의 나머지보다 매끈하거나 선명해 보이면 Pro로 넘어갑니다. 두 사진의 피부톤이나 조명 색이 확실히 다르면 Plus로 넘어갑니다. 아바타 변형 200개는 Face Swap에서 $2.60, Pro에서 $32입니다. 가장 어려운 쌍을 둘 다로 시험해 보세요. Plus에는 효과가 없는 prompt 필드가 있으니 빼고, 안경이나 표정은 대상 사진에 넣으세요.

Video Face Swap은 원본 클립을 10초 단위 블록으로 과금합니다. 12초 클립은 20초분($0.52)으로 청구됩니다. 40초 클립은 $1.04입니다. 제출 시 40초 견적($1.04)을 잠가 두고, 작업이 정산되면 차액을 해제합니다. 제출하기 전에 블록 경계에 맞게 자르세요.

엔드포인트가 실제 얼굴에 대해 무엇을 하는지

이 엔드포인트는 규제 없이 등재되어 있습니다. SpicyAPI는 요청별 얼굴 스캔이나 실인물 확인을 추가하지 않습니다. 실패는 대개 입력 쪽 문제입니다(감지되는 얼굴 없음, 접근할 수 없는 파일). 다만 개별 모델이 요청을 거절할 수는 있습니다. 허용 가능한 사용 정책은 사칭, 동의 없는 사적 또는 성적 용도의 실인물 활용, 미성년자와 관련된 모든 행위를 금지합니다. 신고가 있으면 SpicyAPI는 저장된 자산을 삭제하고 접근을 정지할 수 있습니다. 공개 사진이나 과거의 관계는 동의가 아닙니다. 동의 기록은 사용자가 보관하며, 업로드 버튼보다 먼저 있어야 합니다.

• 로그인한 사용자가 두 이미지 모두와 이 용도에 대해 대상자의 허가를 받았음을 확인합니다. 확인 내용은 프로젝트에 함께 보관합니다(누가, 어떤 자산, 어떤 용도, 언제).
• 미성년자의 이미지는 쓰지 않습니다. 실인물을 사칭해 속이는 용도도 쓰지 않습니다.

이 기록은 프롬프트, 분석 이벤트, 로그가 아니라 제품 기록으로 보관하세요.

실패하지 않을 입력 준비하기

조정할 강도 설정이 없으므로, 결과가 나쁘면 입력 쌍을 바꿔야 합니다.

• 정면으로 크고 선명한 얼굴. 과도한 측면 각도, 동작 블러, 촘촘한 가림(손, 마스크, 큰 선글라스), 지나치게 작은 얼굴은 전사 품질을 떨어뜨리거나 요청을 실패시킵니다. 크고 선명한 정면 레퍼런스 얼굴이 가장 좋은 결과를 냅니다.
• 같은 조명 방향. 교체는 대상의 조명을 다시 계산하지 않으므로, 반대쪽에서 비친 레퍼런스는 턱선에 이음새로 나타납니다. 방향과 대략의 피부톤을 맞추거나 다른 레퍼런스를 고르세요. Plus는 피부톤만 조정하며, 조명 방향 불일치를 고치지는 않습니다.
• 이미지당 얼굴 하나. 단체 사진에서는 Face Swap과 Video Face Swap이 face_mapping을 받습니다. 최대 10개 항목이며, 각 항목이 레퍼런스 얼굴과 대상 얼굴을 짝지어 검출 순서로 0부터 번호를 매깁니다. 이미지를 바꿀 때마다 번호를 다시 확인하세요. Plus와 Pro는 얼굴 하나를 전제로 하므로 먼저 잘라내세요.

``json "face_mapping": [{ "reference_face_index": 0, "target_face_index": 1 }] ``

이는 레퍼런스 얼굴 0을 대상 이미지에서 두 번째로 발견된 얼굴에 적용합니다. 얼굴 하나만 교체하려면 이 필드를 빼세요.

• 파일 직접 링크. 이미지 URL은 로그인 없이 파일로 연결되어야 합니다. 영상에서는 클립을 재생하는 페이지가 클립이 아니라 HTML을 반환하며, 그 호출은 과금이 취소된 채 실패합니다. 대신 파일을 업로드하세요.
• 역할은 바꿔 쓸 수 없습니다. image_url은 바뀌는 이미지이고, reference_image_url은 얼굴을 제공합니다. 둘을 바꾸면 결과만 다른 유효한 요청이 되어 오류를 반환하지 않으므로, 방향이 뒤집힌 교체는 모델 버그처럼 보입니다.

영상 제한 사항은 MP4 최대 90 MB와 3~40초, 레퍼런스 이미지는 JPG, PNG 또는 WEBP 최대 10 MB입니다. 얼굴은 화면 안에서 크게 유지하고, 오랫동안 고개를 돌린 상태로 두지 마세요. 이 엔드포인트는 화면에 한 사람만 있을 때 가장 잘 작동합니다. 여러 사람이 나오는 클립이면 face_mapping을 추가하거나(위와 같은 형태, 검출 순서로 번호 매김) 그 사람만 잘라내세요.

먼저 Playground에서 시험하기

Face Swap 작업 페이지를 열고 Playground 탭(설정, 견적, 실행)을 사용하세요. 대상 이미지와 레퍼런스 얼굴 이미지를 입력하고, 설정에 대한 가격 견적을 확인한 뒤 실행합니다. 코드를 쓰기 전에 가장 어려운 쌍을 여기서 시험해 보세요. Playground에서 틀린 결과는 API로도 틀리고, 해결책은 다른 입력 쌍입니다. Head Swap에도 머리 전체 교체용 같은 탭이 있습니다.

그다음 코드에서 호출하기

Python SDK(pip install spicyapi)를 설치하고, 환경에 SPICY_API_KEY를 설정한 뒤 실행하세요.

import json
import uuid
from pathlib import Path
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
job_file = Path("avatar-8841-layout-02-v1.json")  # keep this file to resume this job

if job_file.exists():
    job = json.loads(job_file.read_text())
else:
    target = client.upload_file("./layout-02.png")
    face = client.upload_file("./approved-portrait.png")
    job = {
        "key": str(uuid.uuid4()),
        "input": {"image_url": target["uri"], "reference_image_url": face["uri"],
                  "style": "realistic", "seed": 4242},
    }
    job_file.write_text(json.dumps(job))  # persist the exact key and payload BEFORE submit

if "taskId" not in job:
    task = client.create_task(
        model="spicyapi/face-swap-v1/edit", input_data=job["input"],
        idempotency_key=job["key"],
    )
    job["taskId"] = task["taskId"]
    job_file.write_text(json.dumps(job))

print("Resume task:", job["taskId"], flush=True)
final = client.wait_for_terminal(job["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {job['taskId']} ended as {final['state']}")
assets = output_assets(final)
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 {job['taskId']} has no ready output; check this task, not a new run")
print(assets[0]["url"])  # copy it to your own storage now

작업 파일 하나당 프로세스 하나를 실행하세요. 대기가 시간 초과되면 같은 파일로 다시 실행해 저장된 작업을 이어가세요. 제출 자체가 ID를 반환하기 전에 시간 초과됐다면, 파일을 보관하고 재시도 전에 그 요청을 대조하세요. 멱등성 보호는 영구적이지 않습니다. 새 유료 요청을 의도할 때만 새 작업 파일 이름을 사용하세요.

업로드, 대기, 오류, 재시도는 Subject Swap 가이드와 Python SDK 레퍼런스에 정리되어 있습니다. Video Face Swap은 video_url과 reference_image_url을 쓰는 spicyapi/face-swap-video-v1/video-edit를 사용합니다.

에이전트에게 일 시키기

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

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

``bash spicyapi files upload ./layout-02.png # prints a spicy:// URI SWAP_REQUEST_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')" printf 'Save this request key: %s\n' "$SWAP_REQUEST_KEY" spicyapi tasks create --model spicyapi/face-swap-v1/edit \ --input-file input.json --idempotency-key "$SWAP_REQUEST_KEY" --wait ``

input.json에는 위와 같은 input 객체를 spicy:// URI로 넣습니다. 이 블록은 새 작업을 시작합니다. 출력된 키와 작업 ID를 보관하세요. 시간 초과 후에는 새 키로 블록을 다시 실행하는 대신 그 작업을 이어가세요.

• MCP 서버. 어시스턴트에 MCP 서버를 추가한 뒤 이렇게 물어보세요. "Swap the face in ./layout-02.png for the one in ./approved-portrait.png with Face Swap." 그러면 spicyapi_upload_file을 호출하고, 이어서 spicyapi_task_create(가격 확인을 위해 멈춥니다)를 호출한 뒤, spicyapi_task_wait를 호출합니다.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill는 Agent Skill을 설치합니다. 이는 코딩 어시스턴트에 최신 스키마를 읽고, 멱등성 키를 재사용하고, 추측 대신 결과를 저장하는 법을 가르칩니다. 그 자체로 작업을 실행할 수는 없으므로 CLI나 MCP와 함께 쓰세요.

동의 기록과 결과를 자체 저장소로 복사하는 일은 에이전트의 호출에도 사용자 자신의 호출과 똑같이 적용됩니다.

끝내기 전에 확인하기

succeeded는 생성이 끝났다는 뜻입니다. 다운로드 전에 자산에 쓸 수 있는 URL이 있고 pending과 unavailable이 모두 거짓인지 확인하세요. pending이 참인 동안이나 URL이 없으면 같은 작업을 계속 조회하세요. 전달 준비가 되었다고 해서 이미지가 승인된 것은 아닙니다. 영상에서는 첫 프레임뿐 아니라 컷과 빠른 동작도 확인하세요. 유사도 점수는 진단 신호이지 동의나 게시 승인이 아닙니다.

다음 행동을 바꾸는 확인 두 가지입니다.

• 머리카락이 디자인의 일부인 경우(게임 캐릭터, 마스코트). Face Swap은 대상의 머리 스타일을 유지하므로 새 얼굴이 옛 머리카락 아래에 놓입니다. 대신 Head Swap을 쓰고, 캐릭터 보드의 고정 이미지를 레퍼런스로 삼아 각 결과물을 보드와 비교하세요. 안정적인 구도에서 얼굴이 흔들리면 동일성 문제이고, 그 반대는 구도 문제이며, 재시도는 둘 중 하나만 고칩니다.
• 여러 레이아웃에 쓰는 한 장의 초상. 같은 레퍼런스와 같은 seed로 레이아웃마다 Face Swap을 한 번씩 실행합니다. 게시할 크롭으로 초상과 비교했을 때 얼굴이 알아볼 수 있고 안경과 머리선이 흔들리지 않았으며 추가 사람이 나타나지 않으면 결과를 받아들이세요. 그와 함께 레퍼런스 리비전, 대상 리비전, 작업 ID를 보관하세요.

전달하기: 결과는 직접 복사하세요

업로드한 소스는 하루 뒤에 삭제되고, 결과는 최대 14일 뒤에 삭제됩니다(retention.outputsExpireAt에 정확한 시각이 있습니다). 결과를 내려받아 직접 보관하세요. 결과 링크는 약 20분 동안만 유지됩니다. 보존 가이드를 참고하세요.

문제가 생길 때

FAQ

API는 실제 사람의 얼굴을 거절하나요?

SpicyAPI는 확인하지 않습니다. 실인물 확인도 요청별 스캔도 없고, 실패는 대개 입력 쪽 문제입니다. 개별 모델은 그래도 거절할 수 있으며, 허용 가능한 사용 정책은 사칭과 동의 없는 사적 사용, 미성년자를 금지합니다. 권한 기록은 직접 만드세요.

영상과 이미지를 한 번의 호출로 보낼 수 있나요?

Video Face Swap에서는 가능합니다. MP4 하나와 레퍼런스 사진 한 장입니다. 한 클립에 여러 사람이 있으면 그곳에서 face_mapping을 쓰거나, 머리 전체가 필요하면 2단계 Video Head Swap 흐름을 쓰세요.

호스팅 API와 셀프 호스팅 오픈 소스 교체 중 무엇인가요?

호스팅 엔드포인트는 이미지당 $0.013이고, GPU 준비와 모델 유지 관리를 없애 줍니다. 셀프 호스팅은 이미지당 요금을 GPU와 운영 비용으로 바꿉니다. 더 저렴한지는 처리량과 이용률에 달렸습니다. 안정적으로 많은 양이 들어오면 이 비용을 더 많은 이미지에 분산할 수 있지만, 동의와 보존 통제는 여전히 직접 유지해야 합니다.

일반적인 이미지 편집 API와 같은 것인가요?

아닙니다. 교체 엔드포인트는 이미지 두 장(또는 이미지 한 장과 클립 한 개)을 받고, 프롬프트도 마스크도 요구하지 않으며, 각 엔드포인트가 대상에서 무엇을 남길지 정합니다. Face Swap은 머리카락을 남기고 Head Swap은 이를 대체합니다. 같은 입력 쌍이라도 검토 통과 여부가 서로 다를 수 있으니, 먼저 엔드포인트를 고르세요.

원본 초상 이미지를 결과물과 함께 보관해야 하나요?

분명한 이유와 공개된 보존 정책이 있을 때만 보관하세요. SpicyAPI의 업로드 소스는 어차피 하루 뒤에 삭제되므로, 각 초상의 영구 사본 대신 레퍼런스와 대상의 리비전 ID 그리고 작업 ID를 계보로 보관하세요.

웹훅이 필요한가요, 폴링만으로 충분한가요?

폴링만으로도 동작하며 복구 경로입니다. 몇 초마다 읽거나, 짧은 이미지 교체에서는 createTask에 wait(최대 60초)를 넣으세요. 지연을 줄이려면 웹훅을 추가하고, 각 이벤트는 한 번만 저장하며, 놓친 콜백의 대조에는 폴링을 사용하세요.

답할 수 있어야 할 것

팀이 어떤 이미지가 사용됐는지, 어떤 리비전이 들어갔는지, 작업이 한 번만 접수됐는지, 왜 결과물이 전달됐는지, 어떻게 제거되는지를 설명할 수 있을 때 얼굴 교체 기능은 신뢰를 얻습니다. 동의 기록, 멱등성 키, 자체 저장소, 검토 단계가 그런 답을 만들어 냅니다.