소개
이 엔드포인트가 하는 일
영상의 주 피사체를 그 뒤의 모든 것과 분리합니다. 그린 스크린도, 영역 선택도 필요 없습니다. 머리카락, 털, 헐렁한 천은 부드러운 가장자리를 유지합니다.
중요한 입력
video_url에는 120초 이하 클립 하나를 넣습니다. output_format으로 결과를 mp4, webm, matte 중에서 정합니다. mp4일 때는 background_image_url 또는 background_video_url을 더할 수 있습니다. resolution은 480p나 720p입니다.
받게 되는 것
원본 화면비와 길이를 유지하고 원래 소리가 담긴 영상 1개입니다.
| 항목 | 값 |
|---|---|
| 입력 | 영상 |
| 출력 | 영상 |
| 엔드포인트 | 영상 편집 |
| 배경 | 지정한 이미지 또는 영상(mp4 전용), 없으면 흰색 |
| 해상도 | 480p 또는 720p, 원본 화면비 유지 |
| 요금 | 원본 초 수 × 선택한 해상도 단가, 최소 3초 |
핵심 기능 및 하이라이트
바닷가 테라스에서 도시 옥상으로
바다가 내려다보이는 테라스에 선 여성의 5초 클립에 해 질 녘 옥상 영상을 배경으로 보냈습니다. 결과물에서 여성은 옥상 위에 서 있었고, 긴 머리카락은 뭉치지 않고 가닥가닥 살아 있었으며, 뒤로는 풍경이 움직이고 원래 소리도 그대로였습니다. 정지 이미지를 보내도 같은 방식으로 합성되고, 배경을 아무것도 보내지 않으면 흰 배경의 MP4가 돌아옵니다.
직접 합성할 수 있는 흑백 매트
matte를 고르면 피사체는 흰색, 나머지는 검은색인 MP4가 나오며 길이와 프레임 속도는 원본과 같습니다. 루마 키를 지원하는 편집 프로그램에서 원본 클립과 짝지어 쓰면 됩니다.
진짜 알파 채널이 담긴 WebM
webm을 고르면 배경이 투명한 VP9 파일이 되어 게임 화면, 슬라이드, 다른 장면 위에 바로 얹을 수 있습니다. Chrome, Edge, Firefox에서는 투명하게 보이지만 Safari는 같은 파일을 검은 배경으로 재생합니다.
요청 파라미터
| 파라미터 | 필수 | 설명 |
|---|---|---|
video_url | 예 | 처리할 클립. MP4나 WebM 업로드 또는 파일 직접 링크이며 120초 이하입니다. 1자 이상 |
output_format | 아니요 | mp4(기본값)는 피사체를 지정한 배경 이미지·영상 또는 흰색 위에 돌려줍니다. webm은 투명도가 있는 VP9를 돌려줍니다(Safari에서는 검은 배경). |
background_image_url | 아니요 | 선택 사항. 피사체 뒤에 놓을 JPEG, PNG, WebP로 화면을 꽉 채우도록 확대됩니다. 1자 이상 |
background_video_url | 아니요 | 선택 사항. 피사체 뒤에 놓을 MP4나 WebM으로 화면을 꽉 채우도록 확대되고 클립보다 짧으면 반복됩니다. 1자 이상 |
resolution | 아니요 | 출력 크기: 480p 또는 720p(기본값). 원본 화면비를 유지합니다. |
요금
원본 클립의 초 수에 선택한 해상도의 초당 요금을 곱해 과금하며, 초는 올림하고 최소 3초입니다. 120초를 넘는 클립은 접수 단계에서 거부됩니다. 출력 형식과 배경은 요금을 바꾸지 않습니다. 실패한 요청은 과금되지 않습니다.
| 사양 | 요금 |
|---|---|
| $0.024 / 초 |
| $0.048 / 초 |
활용 사례
브랜드 세트 앞의 토킹 헤드
평범한 방에서 찍은 진행자를 스튜디오 느낌의 정지 이미지나 반복 재생되는 영상 배경 앞에 세울 수 있습니다. 그린 스크린도 재촬영도 필요 없습니다.
편집과 방송용 오버레이
댄서, 반려동물, 제품을 투명 WebM으로 만들면 VP9 알파를 읽는 편집 프로그램에서 게임 화면이나 슬라이드, 다른 장면 위에 올릴 수 있습니다.
합성용 키 트랙
매트 출력은 After Effects, DaVinci Resolve, Nuke 방식의 작업 흐름에서 원본 클립과 짝지을 수 있는 깔끔한 흑백 트랙입니다.
프롬프트 가이드 및 실전 팁
피사체가 뚜렷한 클립 올리기
피사체는 자동으로 감지되므로 프롬프트도, 클릭으로 고르는 과정도 없습니다. 카메라 앞에 사람이나 물체가 하나만 있을 때 가장 깔끔하게 잘립니다. 클립은 최대 120초까지 됩니다.
받고 싶은 결과 고르기
새 배경의 완성 컷은 mp4, 투명도가 필요하면 webm, 편집 프로그램에서 키 트랙을 쓰려면 matte입니다. 배경 이미지와 배경 영상은 mp4일 때만 쓰입니다.
480p로 확인하고 720p로 완성하기
두 크기 모두 원본 화면비를 유지합니다. 720p의 초당 요금은 480p의 두 배이니, 먼저 짧게 480p로 잘린 모양을 확인해 보세요.
소개
Video Background Remover Pro는 평범한 클립을 받아 카메라 앞의 사람이나 물체를 찾고 주변 장면에서 떼어 냅니다. 무엇을 받을지는 직접 정합니다. 새 배경 위의 피사체, 투명 배경만 남은 피사체, 또는 편집 프로그램에서 키로 쓸 흑백 매트입니다.
요청
{
"video_url": "https://example.com/beach.mp4",
"background_video_url": "https://example.com/city-lights.mp4",
"output_format": "mp4",
"resolution": "720p"
}
필수 값은 video_url뿐입니다. output_format의 기본값은 mp4, resolution은 720p입니다. background_image_url과 background_video_url은 둘 중 하나만, 그리고 mp4일 때만 보내세요. 둘 다 없으면 피사체가 흰 배경에 놓입니다.
세 가지 출력
mp4: 완성된 장면. 배경 이미지는 화면을 꽉 채우도록 확대되고, 배경 영상도 같은 방식으로 확대되며 클립보다 짧으면 반복됩니다.webm: 알파 채널이 있는 VP9. Chrome, Edge, Firefox에서는 투명하게 보이고 Safari에서는 검은 배경으로 재생됩니다.matte: 피사체는 흰색, 나머지는 검은색인 MP4로, 원본과 프레임 단위로 맞춰져 있습니다.
테스트에서 확인한 것
낮게 걸린 해를 등지고 바람에 머리카락이 날리는 여성을 담은 16:9, 3초짜리 해변 클립으로 시험했습니다. 480p에서는 모든 출력이 854×480·24fps로, 720p에서는 1280×720으로 돌아왔고 처리에는 클립당 약 1~2분이 걸렸습니다. 더 넓은 2:1 테라스 클립은 906×452·25fps로 돌아왔습니다. 크기는 높이를 고정하지 않고 선택한 설정의 픽셀 수에 맞춰 정해지며 원본 프레임 속도는 그대로입니다. 매트에서는 가는 머리카락도 따로따로 남았고, WebM은 실제 알파 채널과 함께 디코딩되었으며, MP4에는 원래 소리가 있었습니다. 2초 클립은 최소 단위인 3초로 과금되었습니다.
작업 흐름
호출은 비동기입니다. 작업을 만들고 끝날 때까지 폴링한 뒤 SpicyAPI 저장소에서 영상을 내려받으세요. 실패한 요청은 과금되지 않습니다.
팁
- 요금은 원본 길이를 따르므로 필요한 부분만 잘라서 올리세요.
- 피사체가 하나로 분명할 때 가장 잘 됩니다. 화면에 여러 사람이 있으면 어느 쪽을 피사체로 볼지는 도구가 정합니다.
- Safari까지 포함한 브라우저에서 투명하게 보여야 한다면 WebM 대신 매트와 원본 클립을 함께 쓰세요.
API 빠른 시작
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/background-remover-video-pro/video-edit",
"input": {
"output_format": "mp4",
"resolution": "720p",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
인증, 전체 스키마, 폴링과 오류 처리는 API 레퍼런스에서 확인하세요.



