Morfran API 레퍼런스

기본 URL은 https://api.morfran.com이에요. 모든 요청은 X-API-Key 헤더에 키를 담아 보내요. 키는 대시보드에서 만들 수 있어요. 전체 스키마는 /openapi.json(OpenAPI 3)에 있어요.

X-API-Key 인증

curl https://api.morfran.com/v1/effects \
  -H "X-API-Key: $MORFRAN_KEY"

크레딧과 오류

크레딧은 완성된 이미지에 대해서만 차감돼요. 오류는 상태 코드와 메시지가 담긴 JSON으로 반환돼요.

상태의미조치 방법
401API 키가 없거나 잘못됨X-API-Key 헤더를 확인하세요
402크레딧 부족크레딧 팩을 구매하세요
422사진에서 얼굴을 찾을 수 없음얼굴 하나가 선명하게 나온 사진을 보내 주세요

GET /v1/effects

적용 가능한 효과 목록(slug, 이름, 카테고리, 커버 이미지)을 반환해요. 무료예요.

curl https://api.morfran.com/v1/effects \
  -H "X-API-Key: $MORFRAN_KEY"

POST /v1/effects/{slug}

사진 한 장에 효과 하나를 적용하고 CDN 링크를 반환해요. "quality": "standard"는 11크레딧, "pro"는 29크레딧이에요.

필드타입참고
slugpathGET /v1/effects에서 가져와요. 예: 80s-yearbook
image_urlstring공개 JPG, PNG 또는 WebP
qualitystringstandard(기본값) 또는 pro
curl -X POST https://api.morfran.com/v1/effects/80s-yearbook \
  -H "X-API-Key: $MORFRAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://…/me.jpg","quality":"standard"}'

{ "status": "done",
  "result_url": "https://cdn.morfran.com/…",
  "credits_used": 11,
  "credits_left": 39 }

POST /v1/face-swap

SourceImageUrl의 얼굴을 TargetImageUrl에 합성해요. 5크레딧. 단체 버전인 /v1/face-swap/group은 최대 8명(MaxFaces)의 얼굴을 10크레딧에 바꿔요. 오래 걸리는 작업은 task id를 반환하며, 결과는 GET /v1/face-swap/{taskId}에서 확인해요.

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

POST /v1/transcribe

오디오 또는 영상 파일의 음성을 타임스탬프가 있는 구간별 텍스트로 바꿔요. media_url(또는 media_type와 함께 media_base64)을 보내세요. 선택 사항: 힌트로 쓰는 language(ISO 639-1), 같은 호출에서 번역하는 translate_to, timestamps(기본값 true).

시작된 1분마다 2크레딧, 최소 1분이에요. 번역은 분당 1크레딧이 추가돼요. 파일은 최대 10분, 50MB까지예요. 음성이 없으면 422가 반환되고 과금되지 않아요.

curl -X POST https://api.morfran.com/v1/transcribe \
  -H "X-API-Key: $MORFRAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_url":"https://…/interview.mp3","translate_to":"en"}'

{ "success": true,
  "language": "de",
  "duration_seconds": 184,
  "billed_minutes": 4,
  "credits_used": 12,
  "text": "…",
  "segments": [{ "start": 0.0, "end": 4.2, "text": "…" }],
  "translation": { "language": "en", "text": "…", "segments": [ … ] } }

POST /v1/tts

텍스트(최대 4,000자, 언어 자동 감지)를 자연스러운 음성으로 바꾸고 WAV 링크를 반환해요. GET /v1/tts/voices에서 voice를 고르고(30개 음성, 무료), quality는 standard 또는 pro, 필요하면 "밝게" 같은 읽기 style을 지정하세요.

Standard는 시작된 1,000자마다 5크레딧, Pro는 7크레딧이에요. 실패한 요청은 과금되지 않아요. 오디오 파일은 1시간 동안 보관돼요.

curl -X POST https://api.morfran.com/v1/tts \
  -H "X-API-Key: $MORFRAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Welcome to Morfran.","voice":"Kore","quality":"standard"}'

{ "success": true,
  "audio_url": "https://cdn.morfran.com/…/speech.wav",
  "duration_seconds": 2.1,
  "characters": 19,
  "billed_units": 1,
  "credits_used": 5 }

POST /v1/ocr

이미지나 PDF(최대 20페이지, 20 MB)의 텍스트를 읽어요. image_url 또는 image_base64를 보내세요. JPEG, PNG, WebP, HEIC, PDF는 파일 자체로 판별해요. format은 text(기본값) 또는 표를 유지하는 markdown이에요. language는 선택 사항인 힌트예요.

시작한 10페이지마다 1크레딧이에요. 이미지는 1페이지로 계산해요. PDF의 페이지는 --- 줄로 구분돼요. 실패한 요청은 과금되지 않아요.

curl -X POST https://api.morfran.com/v1/ocr \
  -H "X-API-Key: $MORFRAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://…/invoice.pdf","format":"markdown"}'

{ "success": true,
  "format": "markdown",
  "pages": 3,
  "text": "…",
  "credits_used": 1 }

POST /v1/background-removal

사진의 배경을 지우고 원본 크기의 투명 PNG를 돌려줘요(긴 변 최대 4,096 px). image_url 또는 image_base64를 보내세요(JPEG, PNG, WebP, HEIC, 최대 20 MB).

이미지당 1크레딧이에요. 실패한 요청은 과금되지 않아요. 결과 파일은 1시간 동안 보관돼요.

curl -X POST https://api.morfran.com/v1/background-removal \
  -H "X-API-Key: $MORFRAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url":"https://…/product.jpg"}'

{ "success": true,
  "image_url": "https://cdn.morfran.com/…/cutout.png",
  "width": 2048,
  "height": 1536,
  "credits_used": 1 }

GET /v1/credits/balance

현재 크레딧 잔액. 무료예요.

curl https://api.morfran.com/v1/credits/balance \
  -H "X-API-Key: $MORFRAN_KEY"

AI 에이전트용 MCP 서버

Claude, Cursor 또는 Model Context Protocol을 지원하는 모든 에이전트에서 Morfran을 사용하세요. 서버 주소는 https://api.morfran.com/mcp(Streamable HTTP)이며, REST API와 같은 API 키와 같은 크레딧 가격을 사용해요. 실패한 작업은 과금되지 않아요.

도구: list_effects, apply_effect (slug, image_url, quality), get_effect_task, face_swap (source_image_url, target_image_url), get_face_swap_result, detect_faces, get_credit_balance.

claude mcp add --transport http morfran https://api.morfran.com/mcp \
  --header "X-API-Key: $MORFRAN_KEY"

기타 클라이언트: 이 URL과 X-API-Key 헤더(또는 Authorization: Bearer <key>)로 HTTP MCP 서버를 추가하세요.

공식 MCP Registry에 com.morfran/morfran으로 등록되어 있어요.

부동산 (출시 예정)

가상 스테이징과 8초 매물 영상(영상당 118크레딧)은 아직 API에 없어요. 출시되면 OpenAPI 스키마에 추가돼요.