얼굴 바꾸기 API가 하는 일
얼굴 바꾸기 API는 이미지 두 장을 받아 새 이미지 한 장을 돌려줘요. 소스 이미지에는 사용하고 싶은 얼굴이 있어요. 타깃 이미지는 바꾸고 싶은 사진이에요. API는 타깃에서 얼굴을 찾아 소스의 얼굴로 바꾸고, 피부 톤과 빛, 각도를 맞춰 결과가 한 장의 사진처럼 보이게 해요.
개발자들은 개인 맞춤 인사 카드, "포스터에 내가 등장" 캠페인, 아바타·프로필 도구, 게임 캐릭터, 행사용 포토부스 앱 같은 곳에 이 API를 써요. 직접 모델을 학습시키고 호스팅하는 대신 HTTP 요청 하나만 보내면 이미지를 받을 수 있어요.
시작하기 전에
세 가지가 필요해요.
- Morfran 계정. 새 계정에는 무료 크레딧 50개가 지급돼요. 1인 얼굴 바꾸기 10번에 충분한 양이에요.
- API 키. 대시보드의 API 키에서 만드세요. 키는 서버에 보관하고, 브라우저나 모바일 앱 코드에는 절대 넣지 마세요.
- 공개된 이미지 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 요청을 보여 줘요.