동영상·이미지에 워터마크 추가 — 로고·텍스트 오버레이 API
POST 요청 한 번으로 어떤 동영상이나 이미지에도 로고 이미지나 텍스트를 오버레이해요. position, opacity, scale을 요청에서 바로 설정하면 fotovid가 호스팅하는 파일을 바로 받아 쓸 수 있어요.
curl -X POST https://api.fotovid.co/v1/video/watermark \
-H "Authorization: Bearer p6_YOUR_KEY_ID:YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{
"source_url": "https://cdn.yoursite.com/clip.mp4",
"params": {
"type": "image",
"watermark_image_url": "https://cdn.yoursite.com/logo.png",
"position": "bottom-right",
"opacity": 0.7,
"scale": 0.2
}
}'serverless에서 워터마킹이 번거로운 이유
워터마킹은 별거 아닌 것처럼 보이지만, serverless 함수 안에서 직접 돌리려는 순간 이야기가 달라져요. ffmpeg의 overlay 필터는 전체 바이너리와 로고를 쓰기 가능한 디스크에 올려둬야 하고, 파일 전체를 디코딩한 뒤 다시 인코딩해요. 짧은 클립을 넘어서는 순간부터 Lambda나 Vercel의 실행 시간 제한과 메모리 한도를 예사로 넘어버려요. 결국 구석에 로고 하나 찍자고 레이어 번들, 임시 스토리지, 콜드 스타트까지 직접 관리하게 돼요.
- ffmpeg 바이너리와 라이브러리가 일반적인 serverless 크기 제한을 훌쩍 넘길 만큼 배포 용량을 부풀려요
- 전체 길이 동영상을 다시 인코딩하면 함수 타임아웃과 메모리를 초과해요
- 이미지를 오버레이하려면 파일을 받아와 임시 디스크에 올리고 다시 정리하는 작업이 필요해요
- 여러 해상도에서 position, opacity, scale을 픽셀 단위로 정확히 맞추는 건 까다로운 필터 그래프 작업이에요
요청 파라미터
POST /v1/video/watermark & /v1/image/watermark
| Field | Type | Default | Description |
|---|---|---|---|
| source_url* | string (URL) | — | 원본 동영상 또는 이미지의 HTTPS URL |
| params.type | "image" | "text" | "combo" | "text" | 워터마크 종류 |
| params.watermark_image_url | string (URL) | — | 로고 이미지 URL (image/combo일 때 필수) |
| params.text | string | — | 오버레이할 텍스트 (text/combo일 때 필수) |
| params.position | string | "bottom-right" | top-left · top-right · bottom-left · bottom-right · center |
| params.opacity | number | 1 | 0–1 |
| params.scale | number | 0.15 | 원본 대비 워터마크 너비 비율 (0–1) |
3단계로 시작하는 첫 호출
- 1무료 API 키 발급받기
가입 후 키를 발급받으세요. 모든 요청은 Authorization: Bearer p6_<key_id>:<secret> 헤더로 인증해요. 시작할 때 카드 등록은 필요 없고, 사용량은 credits 단위로 차감돼요 ($1 = 100 credits, 워터마크는 1 credit).
- 2원본과 워터마크 파라미터 POST하기
POST /v1/video/watermark 또는 POST /v1/image/watermark를 표준 envelope로 호출하세요: 입력을 가리키는 source_url(https URL)과 params 객체를 함께 보내요. type을 image, text, combo 중 하나로 설정한 뒤 watermark_image_url과(또는) text를 전달하고, position(top-left, top-right, bottom-left, bottom-right, center), opacity(0–1), scale(0–1, 기본값 0.15), padding을 지정하세요. Fotovid가 입력을 내려받아 워터마크를 오버레이한 뒤 동기 방식으로 결과를 반환해요.
- 3반환된 결과 URL 저장하기
응답은 id, type, 그리고 워터마크가 적용된 파일을 가리키는 fotovid 호스팅 url이 담긴 플랫 JSON이에요 (동영상 응답에는 duration도 포함돼요). 파일을 내려받아 직접 저장해두세요 — 호스팅 URL은 만료되므로 영구 저장소가 아니라 전달용으로만 취급하세요.
