영상 자막·워터마크 및 이미지 워터마크 처리를 위한 Video Eraser API
업데이트 · 550W AI Labs에서 제품 사용 절차를 검토했습니다
개발자 API가 제공하는 작업
550W 개발자 API는 서버에서 권한이 있는 영상의 자막·글자 또는 선택한 사각형 안의 워터마크 처리 작업과 이미지 워터마크 작업을 제출할 수 있습니다. API 접근 권한이 원본 콘텐츠에 대한 권리를 부여하지 않으며 결과도 검수해야 합니다.
영상 자막과 워터마크 처리
영상은 MP4 또는 MOV 파일을 /open/uploadVideo에 업로드하거나 외부에서 접근 가능한 HTTPS videoUrl을 /open/submitTask에 전달합니다. 너비, 높이, 길이와 처리할 사각형 좌표를 함께 지정합니다. 작업은 비동기로 진행되며 /open/taskDetail 또는 /open/taskList로 조회합니다.
이미지의 워터마크
/open/removeImageWatermark는 JPG, PNG, BMP, WebP, AVIF, TIFF, SVG 이미지를 받으며 현재 한 장당 50 MB까지 지원합니다. 바로 결과를 받거나 나중에 조회할 작업이 생성될 수 있습니다. 영상 링크에서 워터마크가 포함된 파일을 내려받는 기능은 이 API에 없습니다.
권한이 있는 영상의 자막·글자와 이미지 워터마크에만 API 기능을 연결하세요.
운영 환경에서 안전하게 요청하기
모든 요청에 userNo와 apiKey가 필요합니다. 브라우저나 모바일 앱 코드에 키를 넣으면 노출될 수 있으므로 두 값은 서버에 보관하세요. 영상은 먼저 업로드하거나 공개 HTTP(S) 주소로 지정할 수 있습니다.
| 단계 | 엔드포인트 | 자체 시스템에 저장할 정보 |
|---|---|---|
| 업로드 | /open/uploadVideo | videoUrl, coverUrl, width, height, duration |
| 제출 | /open/submitTask | taskId, Idempotency-Key / idempotencyKey, asset ID |
| 조회 | /open/taskDetail or /open/taskList | status, cost, failCode, failReason, refundStatus |
| 전달 | callbackUrl and resultUrl | 승인된 별도 파일과 검수 기록 |
인증 정보와 원본은 서버에서 관리
/open/submitTask에 width, height, duration 및 x1, y1, x2, y2를 전달합니다. Standard(mode=normal, 기본값)는 선택한 사각형 안쪽을 처리합니다. Protect(mode=protect)는 안쪽을 보존하고 바깥쪽을 처리하며 화질 향상 모드가 아닙니다. 처리 전에 소리를 제거해야 할 때만 removeAudio를 지정하세요.
중복 방지 키를 붙여 제출
작업 생성 시 128자 이내의 Idempotency-Key를 보내세요. 전송 뒤 연결이 끊어지면 같은 작업에 같은 키를 재사용해 중복 청구가 가능한 별도 작업이 생기지 않게 합니다. 반환된 taskId는 자체 자산 ID와 함께 저장하세요.
완료 알림 뒤 상태를 재확인
완료 알림을 받으려면 공개 HTTP(S) callbackUrl을 지정합니다. 웹훅 수신 후 빠르게 응답하고 /open/taskDetail에서 상태를 다시 조회하세요. 알림이 반복되더라도 안전하게 처리하고 지연에 대비한 폴링 경로도 유지합니다.
서버 인증, 중복 방지 키, 저장된 작업 ID와 완료 상태 재조회가 핵심입니다.
입력 조건과 결과 품질 확인
개발자 API의 영상 조건은 브라우저 업로드 흐름과 다릅니다. 현재 API 안내를 확인하고 형식, 길이, 해상도, 비트 심도와 HDR 여부를 제출 전에 검사하세요. 지원하지 않는 파일을 처리 대기열로 보내지 않아야 합니다.
크레딧 사용 전에 입력 검증
자막 뒤의 배경이 움직이면 결과 판단이 어려워질 수 있습니다. 단순한 벽이나 하늘보다 손, 머리카락, 무늬 옷, 반사, 빠른 카메라 이동이 까다롭습니다. 미리보기 한 장으로 판단하지 말고 출력 영상 전체를 살펴보세요.
움직임이 많은 장면은 직접 검수
이미지 작업 비용은 성공한 작업에 대해 현재 API 페이지에 표시된 조건을 확인하세요. 원본을 보관하고 처리 결과는 별도 파일로 관리하세요. 워터마크를 없앨 수 있다는 사실이 저작권이나 상업 이용 권한을 부여하지는 않습니다.
지원하지 않는 입력은 먼저 걸러 내고 중요한 움직임과 겹친 부분은 사람이 확인하세요.
비용과 실패 유형에 맞춰 재시도하기
영상 자막 처리는 길이와 해상도에 따라 과금됩니다. 현재 API 페이지의 요율은 720p 이하 초당 1.3크레딧, 720p 초과 1080p 이하 초당 1.6크레딧입니다. 30초 영상이라면 각각 약 39크레딧과 48크레딧입니다. 대량 제출 전 /open/queryCredits와 최신 요율을 확인하세요.
제출 전 예상 비용 확인
응답의 code와 message, 작업의 status 및 완료 후 resultUrl을 기록합니다. 실패 시 failCode, failReason, refundStatus가 있다면 함께 확인하세요. 일시적인 통신 오류는 간격을 늘려 재시도할 수 있지만 잘못된 매개변수, 미지원 파일, 정지 계정, 잔액 부족을 무조건 다시 보내서는 안 됩니다.
실패 원인별로 다른 조치
제출과 완료까지 걸린 시간, 실패율, 검수 반려율, 승인된 자산 한 건당 비용을 기록하세요. HTTP 성공 건수만으로는 후속 수작업이 늘었는지 알 수 없습니다.
요청 성공보다 검수 후 승인된 결과와 실제 비용을 기준으로 평가하세요.
작은 시험 작업부터 운영하기
550W 개발자 페이지에서 API 키를 만든 뒤 대표 영상을 한 건 보내세요. 작업 조회와 대기·처리 중·성공·실패 상태 표시를 구현하고, 중복 방지 키와 웹훅 및 대체 폴링을 추가하세요. 소규모 작업의 모든 결과를 검수한 다음 동시 처리량을 늘립니다.
동시 작업을 늘리기 전에 전체 흐름 확인
개발과 운영 환경의 통제를 구분하고 노출된 인증 정보는 교체하세요. 원본 접근 권한과 결과 삭제 기준을 정하고, DAM·CMS·현지화 대기열에 연결할 때도 편집 승인 단계를 유지합니다.
자주 묻는 질문
API로 어떤 영상 작업을 보낼 수 있나요?
API는 권한이 있는 영상의 자막·글자 또는 보이는 워터마크 영역을 적합한 MP4/MOV 업로드 파일이나 공개적으로 접근 가능한 videoUrl에서 처리합니다. 처리할 영역의 좌표를 함께 보내야 합니다. 소셜 미디어 게시물 다운로드 기능은 아닙니다. 입력 조건은 최신 API 문서를 확인하세요.
완료 확인에는 폴링과 웹훅 중 무엇을 써야 하나요?
평소에는 웹훅을 사용하고 알림이 지연될 때를 대비해 작업 상세 조회를 통한 폴링도 유지하세요. 중복 알림과 재시도 모두 안전하게 처리해야 합니다.
시간 초과 뒤 중복 청구를 어떻게 막나요?
제출 시 안정적인 Idempotency-Key를 보내고 같은 논리 작업을 다시 시도할 때 동일한 키를 사용하세요.
영상 작업 비용은 어떻게 정해지나요?
현재 API 페이지에는 720p 이하 초당 1.3크레딧, 720p 초과 1080p 이하 초당 1.6크레딧으로 안내됩니다. 비용을 고정하기 전 최신 조건을 확인하세요.
프런트엔드 코드에 API 키를 넣어도 되나요?
안 됩니다. userNo와 apiKey를 자체 서버에 보관하고 허가된 요청만 서버를 통해 전달하세요.