얼굴 바꾸기 API: API 호출 한 번으로 앱에 페이스 스왑 추가하기

얼굴 바꾸기(페이스 스왑) API를 쓰면 앱이 HTTP 요청 한 번으로 한 사람의 얼굴을 다른 사진에 넣을 수 있어요. 이 가이드에서는 curl, JavaScript, Python 요청 예제, 오래 걸리는 작업과 단체 사진을 다루는 방법, 오류의 의미, 비용, 그리고 책임 있게 사용하는 방법을 알려 드려요.

Morfran 팀 · 3분 분량 · 22 11월 2026 업데이트

얼굴 바꾸기 API가 하는 일

얼굴 바꾸기 API는 이미지 두 장을 받아 새 이미지 한 장을 돌려줘요. 소스 이미지에는 사용하고 싶은 얼굴이 있어요. 타깃 이미지는 바꾸고 싶은 사진이에요. API는 타깃에서 얼굴을 찾아 소스의 얼굴로 바꾸고, 피부 톤과 빛, 각도를 맞춰 결과가 한 장의 사진처럼 보이게 해요.

개발자들은 개인 맞춤 인사 카드, "포스터에 내가 등장" 캠페인, 아바타·프로필 도구, 게임 캐릭터, 행사용 포토부스 앱 같은 곳에 이 API를 써요. 직접 모델을 학습시키고 호스팅하는 대신 HTTP 요청 하나만 보내면 이미지를 받을 수 있어요.

시작하기 전에

세 가지가 필요해요.

  1. Morfran 계정. 새 계정에는 무료 크레딧 50개가 지급돼요. 1인 얼굴 바꾸기 10번에 충분한 양이에요.
  2. API 키. 대시보드의 API 키에서 만드세요. 키는 서버에 보관하고, 브라우저나 모바일 앱 코드에는 절대 넣지 마세요.
  3. 공개된 이미지 URL 두 개. JPG, PNG 또는 WebP. 소스에는 카메라를 대체로 바라보는 선명한 얼굴이 하나 있어야 해요.

모든 요청은 키를 X-API-Key 헤더에 담아 보내요. 기본 URL은 https://api.morfran.com이에요.

curl로 첫 얼굴 바꾸기

curl -X POST https://api.morfran.com/v1/face-swap \
  -H "X-API-Key: $MORFRAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"SourceImageUrl":"https://example.com/face.jpg","TargetImageUrl":"https://example.com/photo.jpg"}'

기본적으로 호출은 동기 방식이에요. API가 결과를 기다린 뒤(최대 약 60초) cdn.morfran.com에 있는 완성 이미지 링크와 사용한 크레딧이 담긴 JSON 응답을 돌려줘요. 결과는 1시간 뒤에 삭제되니 이미지는 바로 내려받으세요.

JavaScript(Node.js)로 같은 요청 보내기

const res = await fetch("https://api.morfran.com/v1/face-swap", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.MORFRAN_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    SourceImageUrl: "https://example.com/face.jpg",
    TargetImageUrl: "https://example.com/photo.jpg",
  }),
});
const data = await res.json();
console.log(res.status, data);

키가 노출되지 않도록 이 코드는 브라우저가 아니라 서버에서 실행하세요.

Python으로 같은 요청 보내기

import os
import requests

res = requests.post(
    "https://api.morfran.com/v1/face-swap",
    headers={"X-API-Key": os.environ["MORFRAN_KEY"]},
    json={
        "SourceImageUrl": "https://example.com/face.jpg",
        "TargetImageUrl": "https://example.com/photo.jpg",
    },
    timeout=90,
)
print(res.status_code, res.json())

오래 걸리는 작업: 비동기 모드 사용하기

앱이 열린 요청을 붙잡고 기다리면 안 된다면 URL에 ?async=true를 붙이세요. API가 바로 작업 ID를 돌려줘요. 그다음 작업이 끝날 때까지 몇 초마다 GET /v1/face-swap/{taskId}로 결과를 확인하세요. 작업 큐 뒤에서 쓰거나 내 서버의 요청 타임아웃이 짧을 때 잘 맞아요.

단체 사진: 최대 8명까지 얼굴 바꾸기

팀 사진이나 가족사진에는 POST /v1/face-swap/group을 쓰세요. 호출 한 번으로 최대 8명의 얼굴을 바꾸고, MaxFaces로 한도를 정해요. 단체 얼굴 바꾸기는 10크레딧, 1인 얼굴 바꾸기는 5크레딧이에요. 전체 필드 목록은 API 문서와 OpenAPI 스키마에 있어요.

오류와 크레딧 처리하기

  • 401: API 키가 없거나 잘못됐어요. X-API-Key 헤더를 확인하세요.
  • 402: 크레딧이 부족해요. 대시보드에서 크레딧 팩을 구매하세요.
  • 422: 얼굴을 찾지 못했어요. 사용자에게 얼굴이 하나만 있는 더 선명한 사진을 요청하세요.

실패한 요청에는 요금이 부과되지 않아요. 크레딧은 완성된 이미지에 대해서만 차감되므로 422 이후 다시 시도해도 두 번 청구되지 않아요. 잔액은 언제든 GET /v1/credits/balance로 무료로 확인할 수 있어요.

더 좋은 결과를 위한 팁

  • 선명한 소스 얼굴을 쓰세요. 한 사람, 카메라를 바라보는 얼굴, 뜬 눈, 선글라스 없이, 좋은 빛에서요.
  • 각도를 맞추세요. 정면을 보는 얼굴은 타깃 속 인물도 대체로 카메라를 보는 사진에 가장 잘 어울려요.
  • 얼굴이 충분히 커야 해요. 타깃에서 폭이 몇 픽셀밖에 안 되는 얼굴은 잘 바뀌지 않아요.
  • 비슷한 빛이 도움이 돼요. 자연광에서 찍은 얼굴은 자연광에서 찍은 타깃 사진에서 가장 자연스러워 보여요.
  • 실제 이미지로 테스트하세요. 무료 크레딧 몇 개를 사용자가 올릴 법한 사진에 써 보세요.

동의와 개인정보

얼굴 바꾸기는 동의한 사람의 얼굴에만 하세요. 사람을 속이거나, 다른 사람을 사칭하거나, 실제 인물에게 해를 끼치는 콘텐츠를 만드는 데 얼굴 바꾸기를 쓰지 마세요. 결과를 공개할 때는 AI로 생성했다고 표시하세요. 업로드한 이미지와 결과는 1시간 안에 저장소에서 삭제되고, AI 모델 학습에는 사용하지 않아요. 악용 사례는 문의 페이지로 신고할 수 있으며 48시간 안에 처리돼요.

AI 에이전트에서 사용하기

같은 얼굴 바꾸기를 Morfran의 MCP 서버 https://api.morfran.com/mcp에서도 쓸 수 있어서, Claude 같은 어시스턴트가 내 API 키로 호출할 수 있어요. 설정 방법은 문서의 MCP 섹션에 나와 있어요.

자주 묻는 질문

얼굴 바꾸기 API는 얼마인가요?

1인 얼굴 바꾸기는 5크레딧, 단체 얼굴 바꾸기(최대 8명)는 10크레딧이에요. 새 계정에는 무료 크레딧 50개가 지급돼요. 그 후에는 크레딧 팩을 구매하며, 구독은 없어요. 팩은 가격에서 확인하세요.

얼굴 바꾸기는 얼마나 걸리나요?

대부분의 결과는 약 60초의 동기 대기 시간 안에 돌아와요. 오래 걸리는 작업이나 서버 타임아웃이 짧은 경우에는 ?async=true를 쓰고 작업 ID로 결과를 확인하세요.

이미지를 URL 대신 base64로 보낼 수 있나요?

여기 예제는 공개 URL을 쓰는데, 이게 가장 간단한 방법이에요. OpenAPI 스키마에 이 엔드포인트가 받는 모든 입력 필드가 나와 있어요.

결과는 얼마나 보관되나요?

업로드한 이미지와 결과는 1시간 안에 삭제돼요. 결과 이미지는 받자마자 내 쪽에 저장하세요.

코드를 쓰지 않고도 써 볼 수 있나요?

네. 로그인한 뒤 플레이그라운드를 열어 보세요. 같은 얼굴 바꾸기를 브라우저에서 실행하고 그에 맞는 API 요청을 보여 줘요.