> ## Documentation Index > Fetch the complete documentation index at: https://docs.bizmori.com/llms.txt > Use this file to discover all available pages before exploring further. # 워터마크 삽입 주문 생성 > 이미지와 PDF에 비가시성 워터마크를 삽입하는 주문을 생성합니다. - 주문당 파일 최대 100개, 파일당 문구 1~10개, 문구당 1~1,000자 - 문구마다 `outputs[]`에 별도 결과 파일이 생기며 1크레딧을 사용합니다 - 지원 확장자: `jpg`, `jpeg`, `png`, `webp`, `bmp`, `tif`, `tiff`, `pdf`. BMP는 무압축 24비트 RGB 또는 1·8비트 흑백, TIFF는 단일 페이지 8비트 RGB 또는 1·8비트 흑백(알파 없음)만 처리할 수 있습니다 - 이 범위를 벗어난 BMP·TIFF(다중 페이지, 16비트, 팔레트, 알파, CMYK 등)는 주문이 공개 `errorCode`와 함께 `failed`가 되고 크레딧은 복구됩니다 - `originalFileUrl`이 없는 파일은 `files[].uploadUrl`(900초 유효)로 `PUT` 업로드합니다 - 모든 파일 업로드가 끝나면 처리가 자동으로 시작됩니다. confirm 호출은 없습니다 - 12시간 안에 업로드되지 않은 주문은 `failed`가 됩니다 - [`GET /api/v3/orders/{orderId}`](/ko/api-reference/orders/get-order-v3)로 `status`가 `complete`가 될 때까지 조회한 뒤 다운로드 API를 호출하세요 ## OpenAPI ````yaml ko/api-reference/openapi.yaml POST /api/v3/orders/wtr-embed openapi: 3.0.0 info: title: BIZ MORI API version: 2.0.0 description: > BIZ MORI API는 디지털 콘텐츠 보호를 위한 네 가지 핵심 서비스를 제공합니다: - **Anti-AI**: 이미지를 AI 학습으로부터 보호 - **Watermark Embed**: 이미지에 보이지 않는 디지털 워터마크 삽입 - **Watermark Extract**: 이미지에서 워터마크 추출 및 검증 - **AI Detection**: 이미지가 AI로 생성되었는지 감지 - **테스트 API 키**: `sk_test_` 접두사의 키는 동일한 Bearer 인증을 사용하며, 실제 처리 서비스나 크레딧 사용 없이 주문 흐름을 검증할 수 있습니다. 테스트 업로드는 파일 내용을 폐기하고 결과 파일을 만들지 않습니다 contact: name: BIZ MORI 지원 email: support@bizmori.com license: name: Proprietary url: https://docs.bizmori.com/legal/terms servers: - url: https://api.bizmori.com description: 프로덕션 security: [] tags: - name: Anti-AI description: AI 학습 방지 이미지 보호 주문 - name: Watermark Embed description: 워터마크 삽입 주문 - name: Watermark Extract description: 워터마크 추출 주문 - name: AI Detection description: AI 생성 이미지 감지 주문 - name: Orders description: 주문 조회 및 관리 - name: Webhooks description: 웹훅 설정 및 이벤트 - name: Reports description: 워터마크 추출·AI Detection 주문의 PDF 분석 보고서 paths: /api/v3/orders/wtr-embed: post: tags: - Watermark Embed summary: 워터마크 삽입 주문 생성 description: > 이미지와 PDF에 비가시성 워터마크를 삽입하는 주문을 생성합니다. - 주문당 파일 최대 100개, 파일당 문구 1~10개, 문구당 1~1,000자 - 문구마다 `outputs[]`에 별도 결과 파일이 생기며 1크레딧을 사용합니다 - 지원 확장자: `jpg`, `jpeg`, `png`, `webp`, `bmp`, `tif`, `tiff`, `pdf`. BMP는 무압축 24비트 RGB 또는 1·8비트 흑백, TIFF는 단일 페이지 8비트 RGB 또는 1·8비트 흑백(알파 없음)만 처리할 수 있습니다 - 이 범위를 벗어난 BMP·TIFF(다중 페이지, 16비트, 팔레트, 알파, CMYK 등)는 주문이 공개 `errorCode`와 함께 `failed`가 되고 크레딧은 복구됩니다 - `originalFileUrl`이 없는 파일은 `files[].uploadUrl`(900초 유효)로 `PUT` 업로드합니다 - 모든 파일 업로드가 끝나면 처리가 자동으로 시작됩니다. confirm 호출은 없습니다 - 12시간 안에 업로드되지 않은 주문은 `failed`가 됩니다 - [`GET /api/v3/orders/{orderId}`](/ko/api-reference/orders/get-order-v3)로 `status`가 `complete`가 될 때까지 조회한 뒤 다운로드 API를 호출하세요 operationId: createWatermarkV1EmbedOrder requestBody: required: true content: application/json: schema: type: object required: - idempotencyKey - files properties: idempotencyKey: type: string maxLength: 255 description: >- 멱등성 키. 새 주문마다 새 UUIDv4를 쓰고, 같은 요청을 재시도할 때만 재사용합니다. 같은 키는 기존 주문을 반환하며, 같은 키로 다른 요청 본문을 보내면 `409 WATERMARK_V2_CONFLICT`를 반환합니다. files: type: array minItems: 1 maxItems: 100 description: 한 주문에 이미지와 PDF를 섞을 수 있습니다. items: type: object required: - fileName - watermarks properties: fileName: type: string maxLength: 255 description: >- 확장자를 포함한 파일명. 지원 형식: `jpg`, `jpeg`, `png`, `webp`, `bmp`, `tif`, `tiff`, `pdf` originalFileUrl: type: string format: uri description: >- 원본 파일의 공개 HTTPS URL(선택). 지정하면 BIZ MORI가 파일을 내려받으며(최대 32 MiB, redirect 미지원) 해당 파일의 `uploadUrl`은 발급하지 않습니다. watermarks: type: array minItems: 1 maxItems: 10 description: 삽입할 워터마크 문구. 문구마다 별도 결과 파일이 생성되고 1크레딧을 사용합니다. items: type: object required: - text properties: text: type: string minLength: 1 maxLength: 1000 example: idempotencyKey: f47ac10b-58cc-4372-a567-0e02b2c3d479 files: - fileName: campaign.png watermarks: - text: MORI-2026-001 - fileName: contract.pdf originalFileUrl: https://example.com/contract.pdf watermarks: - text: PARTNER-A - text: PARTNER-B responses: '200': description: 주문 생성, 또는 같은 `idempotencyKey`의 기존 주문 반환 content: application/json: schema: $ref: '#/components/schemas/WatermarkV1OrderResponse' example: data: orderId: '1234567890' status: pending processingDelayed: false expiresAt: '2026-10-08T03:00:00.000Z' files: - fileId: '501' uploadUrl: https://s3.ap-northeast-2.amazonaws.com/... - fileId: '502' uploadUrl: null outputs: - fileId: 501-1 inputFileId: '501' outputIndex: 0 watermarkText: MORI-2026-001 status: pending mediaKind: image - fileId: 502-1 inputFileId: '502' outputIndex: 0 watermarkText: PARTNER-A status: pending mediaKind: pdf - fileId: 502-2 inputFileId: '502' outputIndex: 1 watermarkText: PARTNER-B status: pending mediaKind: pdf result: null reports: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '409': description: 같은 `idempotencyKey`로 다른 요청 본문을 보냄 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: WATERMARK_V2_CONFLICT '429': description: 요청 횟수 초과 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: RATE_LIMIT_EXCEEDED '500': $ref: '#/components/responses/InternalError' '503': description: 워터마크 처리를 일시적으로 사용할 수 없음 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: WATERMARK_V2_UNAVAILABLE security: - BearerAuth: [] x-codeSamples: - lang: curl label: cURL source: | curl -X POST https://api.bizmori.com/api/v3/orders/wtr-embed \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "idempotencyKey": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "files": [ { "fileName": "campaign.png", "watermarks": [ { "text": "MORI-2026-001" } ] }, { "fileName": "contract.pdf", "originalFileUrl": "https://example.com/contract.pdf", "watermarks": [ { "text": "PARTNER-A" }, { "text": "PARTNER-B" } ] } ] }' - lang: javascript label: JavaScript source: > const response = await fetch(`https://api.bizmori.com/api/v3/orders/wtr-embed`, { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ "idempotencyKey": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "files": [ { "fileName": "campaign.png", "watermarks": [ { "text": "MORI-2026-001" } ] }, { "fileName": "contract.pdf", "originalFileUrl": "https://example.com/contract.pdf", "watermarks": [ { "text": "PARTNER-A" }, { "text": "PARTNER-B" } ] } ] }) }); const { data } = await response.json(); // 각 파일을 presigned URL로 PUT 업로드합니다 (files[]는 요청 순서) // await fetch(data.files[0].uploadUrl, { method: 'PUT', body: file }); - lang: python label: Python source: > import requests response = requests.post( f'https://api.bizmori.com/api/v3/orders/wtr-embed', headers={'Authorization': 'Bearer YOUR_API_KEY'}, json={ "idempotencyKey": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "files": [ { "fileName": "campaign.png", "watermarks": [ { "text": "MORI-2026-001" } ] }, { "fileName": "contract.pdf", "originalFileUrl": "https://example.com/contract.pdf", "watermarks": [ { "text": "PARTNER-A" }, { "text": "PARTNER-B" } ] } ] } ) data = response.json()['data'] # 각 파일을 presigned URL로 PUT 업로드합니다 (files[]는 요청 순서) # requests.put(data['files'][0]['uploadUrl'], data=open('campaign.png', 'rb')) components: schemas: WatermarkV1OrderResponse: type: object required: - data properties: data: $ref: '#/components/schemas/WatermarkV1Order' ErrorResponse: type: object properties: code: type: string description: 에러 코드 WatermarkV1Order: type: object description: v3 API로 생성한 비가시성 워터마크 주문 required: - orderId - status - processingDelayed - files - outputs - result - reports properties: orderId: type: string description: 주문 ID status: type: string enum: - pending - inProgress - complete - failed - expired description: | 주문 처리 상태 * `pending` - 파일 업로드 대기 * `inProgress` - 처리 중 * `complete` - 처리 완료. 추출 주문은 `result`에서 결과를 확인합니다 * `failed` - 처리 실패, 또는 12시간 안에 업로드되지 않음 * `expired` - 보관 기한이 지나 파일이 삭제됨 processingDelayed: type: boolean description: 자동 재시도를 모두 소진해 수동 복구를 기다리면 `true`. 주문은 `inProgress`로 유지됩니다 expiresAt: type: string format: date-time nullable: true description: 주문 파일이 삭제되는 시각. 이후 다운로드와 보고서는 `ORDER_EXPIRED`를 반환합니다 files: type: array description: 요청 순서의 입력 파일. 추출 주문은 원본, 검사 파일 순서입니다 items: $ref: '#/components/schemas/WatermarkV1UploadFile' outputs: type: array description: 삽입 결과. 워터마크 문구마다 1개이며 추출 주문은 빈 배열입니다 items: $ref: '#/components/schemas/WatermarkV1Output' result: $ref: '#/components/schemas/WatermarkV1DetectionResult' reports: type: array description: 이 주문으로 요청한 보고서 items: type: object required: - locale - status properties: locale: type: string enum: - ko-KR - en-US - ja-JP status: type: string enum: - queued - processing - completed - failed WatermarkV1UploadFile: type: object required: - fileId - uploadUrl properties: fileId: type: string description: 입력 파일 ID uploadUrl: type: string format: uri nullable: true description: > 파일 업로드용 presigned `PUT` URL(900초 유효). 주문 `status`가 `pending`이고 보관 기한 전이며 업로드 대기 중인 파일에만 발급합니다. `originalFileUrl`로 지정한 파일, 업로드가 끝난 파일, 12시간 업로드 기한을 넘겨 `failed`가 된 주문, 보관 기한이 지난 주문은 `null`입니다. WatermarkV1Output: type: object required: - fileId - inputFileId - outputIndex - watermarkText - status - mediaKind properties: fileId: type: string description: '`{inputFileId}-{순번}` 형식의 결과 파일 ID(`outputs[].fileId`)' inputFileId: type: string description: 이 결과를 만든 입력 파일 ID outputIndex: type: integer minimum: 0 description: 입력 파일 `watermarks` 안에서 해당 문구의 위치 watermarkText: type: string description: 삽입한 워터마크 문구 status: type: string enum: - pending - queued - processing - completed - failed - retry_required description: 이 결과 파일의 처리 상태 mediaKind: type: string enum: - image - pdf WatermarkV1DetectionResult: type: object nullable: true description: 추출 결과 요약. 삽입 주문과 결과가 나오기 전에는 `null`이며 아래 필드만 포함합니다 required: - detectionStatus - reportSupported - watermarkText additionalProperties: false properties: detectionStatus: type: string enum: - detected - not_detected - inconclusive - unsupported - error description: | * `detected` - 워터마크를 찾음 * `not_detected` - 끝까지 검사했으나 워터마크 없음 * `inconclusive` - 후보는 있으나 확신 기준 미달로 판단 불가 * `unsupported` - 처리할 수 없는 입력 (크레딧 환불) * `error` - 검출 처리 실패, 워터마크 없음과 다름 (크레딧 환불) reportSupported: type: boolean description: 이 결과로 보고서를 만들 수 있는지 여부. PDF에서 캡처한 이미지는 `false` watermarkText: type: string nullable: true description: > 검출된 워터마크의 삽입 문구. `detectionStatus`가 `detected`이고, 호출 계정이 직접 삽입했으며 발급 기록이 정확히 1건일 때만 반환합니다. 다른 계정이 삽입한 워터마크 등 그 외에는 `null`입니다. responses: BadRequest: description: 잘못된 요청 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: VALIDATION_FAILED Unauthorized: description: 인증 실패 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: AUTH_NOT_AUTHENTICATED InternalError: description: 내부 서버 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: SERVER_INTERNAL_ERROR securitySchemes: BearerAuth: type: http scheme: bearer description: >- 외부 클라이언트 접근을 위한 Bearer API 키. 일반 키는 `sk_` 접두사를 사용하고, 테스트 키는 `sk_test_` 접두사로 모의 응답을 사용해 실제 처리나 크레딧 사용 없이 주문 흐름을 검증합니다. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.