사전 준비
- BIZ MORI API 키 (여기서 발급)
- 워터마크를 삽입할 이미지 또는 PDF 파일 (
jpg,jpeg,png,webp,bmp,tif,tiff,pdf)
자동 발급된
sk_test_ 키를 사용하면 실제 워터마크 처리나 크레딧 사용 없이 v3 흐름 전체를 검증할 수 있습니다. 테스트 주문은 업로드 후 약 5초 뒤에 완료되며, 다운로드 URL은 실제 결과 대신 고정된 샘플 파일을 반환합니다. 실제로 워터마크가 삽입된 파일이 필요하면 일반 API 키를 사용하세요.동작 방식
- 파일 이름과 파일별 워터마크 문구로 주문을 생성합니다.
- 응답의 프리사인드
uploadUrl로 각 파일을PUT업로드합니다. 모든 파일이 업로드되면 처리가 자동으로 시작되며, confirm 단계는 없습니다. GET /api/v3/orders/{orderId}를 폴링하거나 웹훅을 받아 주문 완료를 기다립니다.- 결과를 다운로드합니다. 한 번의 호출로 결과 파일별 URL과 결과 전체 URL을 함께 받습니다.
1단계: 주문 생성
워터마크 삽입 주문을 생성합니다. 파일마다 워터마크 문구를 1~10개 지정할 수 있으며, 문구 하나마다 결과 파일이 하나씩 만들어지고 1크레딧이 사용됩니다. 아래 요청은 이미지 하나에 문구 두 개를 삽입하므로 결과 파일 2개가 만들어지고 2크레딧이 사용됩니다.files[]는 요청한files와 같은 순서로 반환됩니다. 요청의files[i]파일은files[i].uploadUrl로 업로드하세요.outputs[]에는 워터마크 문구마다 항목이 하나씩 있습니다. 여기의fileId(501-1등)는 이 생성 응답에서만 쓰입니다. 주문 상세와 다운로드 응답은 결과 파일을 숫자로 된fileId로 구분합니다.expiresAt은 주문 파일이 삭제되는 시각입니다. 그 전에 결과를 다운로드하세요.
같은
idempotencyKey는 같은 요청을 재시도할 때만 다시 사용하세요. 이 경우 새 주문을 만들지 않고 기존 주문을 반환합니다. 같은 키로 요청 본문이 다른 요청을 보내면 409 WATERMARK_V2_CONFLICT를 반환합니다.2단계: 파일 업로드
각 파일을 프리사인드uploadUrl로 PUT 업로드합니다. 스토리지로 직접 올리는 업로드이므로 Authorization 헤더는 필요 없습니다.
Content-Type 헤더는 파일 확장자에 맞는 값으로 보내야 합니다. 프리사인드 URL이 이 타입으로 서명되어 있어 다른 값을 보내면 업로드가 거부됩니다.
confirm 단계는 필요 없습니다. 주문의 모든 파일이 업로드되면 처리가 자동으로 시작됩니다.
일반 키의
uploadUrl은 900초 뒤에 만료됩니다. 만료되었다면 GET /api/v3/orders/{orderId}를 호출해 아직 업로드되지 않은 파일의 새 inputFiles[].uploadUrl을 받으세요. 주문 생성 후 12시간 안에 모든 파일을 업로드하지 않으면 주문이 failed가 됩니다. 테스트 키는 1시간 동안 유효한 https://api.bizmori.com/api/v2/test-uploads/{signedToken} URL을 받습니다. 인증 없이 같은 방식으로 PUT하면 되며, 업로드한 파일 내용은 폐기됩니다.3단계: 주문 완료 대기
status가 complete가 될 때까지 주문을 폴링하세요. 폴링 대신 웹훅을 설정하면 order.watermarkEmbed.completed 또는 order.watermarkEmbed.failed 이벤트를 받을 수 있습니다.
주문이
complete가 되면 result.outputFiles[]에 워터마크 문구마다 결과 파일이 하나씩 나옵니다. 주문 상세는 모든 주문 종류에서 같은 형식이며, 전체 필드는 주문 상세 조회를 참고하세요.
processingDelayed가 true이면 자동 재시도가 모두 소진되어 수동 복구를 기다리는 중입니다. 주문은 inProgress 상태로 유지되므로 계속 폴링하거나 웹훅을 기다리세요.
order.watermarkEmbed.failed 웹훅에는 실패 원인을 알려주는 errorCode가 포함됩니다. 이벤트 페이로드와 에러 코드는 웹훅을 참고하세요.
4단계: 결과 다운로드
status가 complete가 되면 다운로드 URL을 요청합니다. 한 번의 호출로 결과 파일별 URL(files[])과 결과 전체를 받는 URL(archiveUrl)을 함께 받습니다. 결과 파일이 하나면 archiveUrl은 그 파일을, 여러 개면 ZIP 파일을 가리킵니다.
files[]는result.outputFiles[]와 같은 결과 파일을 같은 순서로 담고fileId도 같습니다.fileId로 맞춰 보면 각 파일에 어떤 워터마크 문구가 들어갔는지 알 수 있습니다.- URL은 최대 3600초 동안 유효하며, 보관 기한이 먼저 끝나면 그보다 짧습니다. 저장해 두지 말고 다운로드할 때마다 새로 요청하세요.
expiresAt이 지나면 이 엔드포인트는400 ORDER_EXPIRED를 반환합니다.
테스트 주문에서는
archiveUrl과 files[]가 고정된 샘플 파일을 가리킵니다(결과가 여러 개면 ZIP). 실제로 워터마크가 삽입된 파일이 아닙니다.전체 React 예제
위 내용을 모두 하나의 컴포넌트로 연결했습니다: 진행률을 보여주는 단일 파일 업로드, 추가/삭제와 중복 검사가 가능한 워터마크 문구 목록, 백오프 폴링, 누를 때마다 새 URL을 받는 다운로드 버튼까지. React 외에 별도의 의존성은 없습니다.WatermarkEmbedUploader.jsx
import.meta.env.VITE_MORI_API_KEY는 Vite 문법입니다. Next.js에서는 process.env.NEXT_PUBLIC_MORI_API_KEY를, 그 밖의 번들러에서는 클라이언트 코드에 노출하는 방식을 사용하세요. crypto.randomUUID()는 보안 컨텍스트가 필요합니다. HTTPS와 localhost에서는 동작하지만 일반 HTTP로 접속한 LAN 주소에서는 동작하지 않습니다.에러 처리
전체 에러 코드는 에러 코드 페이지를 참고하세요.
v2에서 v3로 마이그레이션
v3의 요청 본문은 v2와 형태가 같습니다. 대부분은 엔드포인트 경로와 결과를 읽는 방식만 바꾸면 됩니다.
달라지지 않는 점: 한 주문에 이미지와 PDF를 섞을 수 있고,
originalFileUrl을 지정하면 업로드를 건너뛸 수 있으며, confirm 호출 없이 처리가 시작됩니다.
v2 지원 종료 후 동작 (2026년 10월 9일 09:00 KST, 00:00 UTC부터):
- 인증·권한 검사는 지금처럼 먼저 수행하므로
401,403오류는 기존과 같습니다. - 인증을 통과한 v2 워터마크 삽입·검출 요청은 live 키와
sk_test_키 모두410 Gone과{ "code": "WATERMARK_V2_API_SUNSET" }을 받습니다.Link헤더가 v3 엔드포인트를 가리키니 v3로 새로 요청하세요. - 그때까지 처리를 시작하지 않은 v2 주문은 처리되지 않고 실패로 확정됩니다. 주문 상세(
errors.errorCode)와 실패 웹훅에WATERMARK_V2_API_SUNSET과 v3 안내 메시지가 담기며, 과금되지 않고 크레딧은 복원됩니다. - 종료 시각에 이미 처리 중인 주문은 결과 기록까지 마칩니다. 이후 새로 다시 실행하지는 않습니다.
- 기존 v2 주문 조회와 이미 생성된 결과·보고서 다운로드는 기존 보존 기간 안에서 계속 이용할 수 있습니다. v2 보고서를 새로 생성하거나 재생성할 수는 없습니다.
Deprecation: true, Sunset: Fri, 09 Oct 2026 00:00:00 GMT, Link 헤더만 추가됩니다.
다음 단계
워터마크 검출
파일에서 워터마크를 검출하고 보고서를 만듭니다.
테스트 API 키
크레딧 사용 없이 v3 흐름을 검증합니다.
웹훅
처리가 끝나면 알림을 받습니다.
API 레퍼런스
v3 워터마크 삽입 엔드포인트의 모든 필드를 확인합니다.