비디오 썸네일 API: 원하는 타임스탬프에서 커버 프레임 추출하기
Fotovid에 타임스탬프를 지정하면 그 프레임을 호스팅 이미지로 캡처해요 — 갤러리 미리보기, 피드 썸네일, 비디오 포스터로 바로 가져다 쓸 수 있어요.
curl -X POST https://api.fotovid.co/v1/video/extract-cover \
-H "Authorization: Bearer p6_YOUR_KEY_ID:YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{
"source_url": "https://cdn.yoursite.com/clip.mp4",
"params": {
"at": 3
}
}'프레임 하나 뽑는 게 왜 생각보다 어려울까요
비디오 썸네일은 개념적으로는 간단해요: 타임스탬프로 이동해서 프레임 하나를 디코딩하고 이미지로 인코딩하면 끝이죠. 하지만 실제로는 직접 ffmpeg를 실행하거나, 기능이 잔뜩 딸린 미디어 플랫폼에 의존해야 해요. ffmpeg 바이너리를 번들링하면 serverless의 크기·메모리 제한을 훌쩍 넘고, 콜드 스타트는 느려지고, 큰 소스를 디코딩하면 함수의 타임아웃을 초과할 수도 있어요. 게다가 전체 툴체인이 필요한 경우는 거의 없어요 — 필요한 건 프레임 하나뿐이니까요.
- ffmpeg 바이너리는 대부분의 serverless 번들에 담기엔 너무 크고, 콜드 스타트 예산을 잡아먹어요
- 프레임 하나를 뽑으려고 큰 비디오를 디코딩하면 함수의 메모리·타임아웃 제한을 초과할 수 있어요
- 소스를 가져오고, 처리를 실행하고, 결과를 직접 어딘가에 업로드하는 과정을 전부 스스로 해야 해요
- 종합 미디어 플랫폼은 포스터 한 장 얻자고 원치도 않는 변환·스토리지·CDN까지 한데 묶어서 제공해요
요청 파라미터
POST /v1/video/extract-cover
| Field | Type | Default | Description |
|---|---|---|---|
| source_url* | string (URL) | — | 소스 비디오의 HTTPS URL (HTTP Range로 읽음) |
| params.at | number | 1 | 프레임을 추출할 비디오 내 시점(초) |
3단계로 알아보는 첫 호출
- 1무료 API 키 발급받기
가입하고 키를 발급받으세요. 모든 요청은 Authorization: Bearer p6_<key_id>:<secret> 헤더로 인증해요. 새로 발급받은 키에는 무료 사용 credits가 기본 제공되므로, 결제 전에 썸네일 연동을 먼저 구현해볼 수 있어요.
- 2POST /v1/video/extract-cover 호출하기
비디오의 https URL을 가리키는 source_url과, 추출할 타임스탬프를 지정하는 params 객체(HH:MM:SS.mmm 형식의 문자열 또는 초 단위 숫자)를 담아 JSON을 전송하세요. Fotovid가 소스를 가져와 해당 시점의 프레임을 디코딩하고, 저희 인프라에서 이미지로 인코딩해요 — 여러분의 스택에는 ffmpeg가 필요 없어요.
- 3반환된 호스팅 이미지 URL 사용하기
응답은 id, type, 추출된 프레임을 가리키는 fotovid 호스팅 url, 그리고 expires_at으로 구성된 플랫 JSON이에요. 이 url을 썸네일이나 포스터로 바로 렌더링하거나, 다운로드해서 직접 관리하는 버킷에 저장하면 수명 주기를 원하는 대로 제어할 수 있어요.
