> ## 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.
# 워터마크 삽입 주문 생성
> 워터마크 삽입 주문을 생성합니다.
- 이미지당 최대 10개의 워터마크 텍스트
- 주문당 최대 100개의 파일
- 지원 이미지 형식 (IMG): jpg, jpeg, png, webp, bmp, tiff
- 지원 문서 형식 (DOCUMENT): pdf
## 입력 모드 (업로드 / URL / 혼합)
입력 모드는 각 파일 객체의 `originalFileUrl` 존재 여부에 따라 결정됩니다:
- **업로드 모드** (`originalFileUrl` 없음): Presigned URL 발급 → 클라이언트가 S3에 업로드 → 처리 자동 시작
- **URL 모드** (`originalFileUrl` 제공): 해당 URL에서 이미지를 다운로드하여 즉시 처리
- **혼합 모드**: 일부 파일은 업로드 모드, 나머지는 URL 모드로 동시 처리
### 동작 방식
| 조건 | 주문 상태 | Confirm 필요 여부 |
|------|---------|-----------------|
| 모든 파일에 `originalFileUrl` 있음 | `pending` | 불필요 (서버 다운로드 후 자동 시작) |
| `originalFileUrl` 없는 파일 존재 | `pending` | 불필요 (업로드 후 자동 시작) |
Anti-AI, AI Detection과 달리 Watermark Embed는 별도의 confirm 단계가 필요하지 않습니다. 파일 업로드가 완료되면 처리가 자동으로 시작됩니다.
## OpenAPI
````yaml /ko/api-reference/openapi.yaml post /api/v2/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로 생성되었는지 감지
contact:
name: BIZ MORI 지원
email: support@bizmori.com
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: 웹훅 설정 및 이벤트
paths:
/api/v2/orders/wtr-embed:
post:
tags:
- Watermark Embed
summary: 워터마크 삽입 주문 생성
description: >
워터마크 삽입 주문을 생성합니다.
- 이미지당 최대 10개의 워터마크 텍스트
- 주문당 최대 100개의 파일
- 지원 이미지 형식 (IMG): jpg, jpeg, png, webp, bmp, tiff
- 지원 문서 형식 (DOCUMENT): pdf
## 입력 모드 (업로드 / URL / 혼합)
입력 모드는 각 파일 객체의 `originalFileUrl` 존재 여부에 따라 결정됩니다:
- **업로드 모드** (`originalFileUrl` 없음): Presigned URL 발급 → 클라이언트가 S3에 업로드 →
처리 자동 시작
- **URL 모드** (`originalFileUrl` 제공): 해당 URL에서 이미지를 다운로드하여 즉시 처리
- **혼합 모드**: 일부 파일은 업로드 모드, 나머지는 URL 모드로 동시 처리
### 동작 방식
| 조건 | 주문 상태 | Confirm 필요 여부 |
|------|---------|-----------------|
| 모든 파일에 `originalFileUrl` 있음 | `pending` | 불필요 (서버 다운로드 후 자동 시작) |
| `originalFileUrl` 없는 파일 존재 | `pending` | 불필요 (업로드 후 자동 시작) |
Anti-AI, AI Detection과 달리 Watermark Embed는 별도의 confirm 단계가 필요하지
않습니다. 파일 업로드가 완료되면 처리가 자동으로 시작됩니다.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- idempotencyKey
- files
properties:
idempotencyKey:
type: string
description: 멱등성 키
files:
type: array
minItems: 1
maxItems: 100
items:
type: object
required:
- fileName
- watermarks
properties:
fileName:
type: string
description: 파일 이름
example: image.jpg
originalFileUrl:
type: string
format: uri
description: |
원본 이미지 URL (선택)
- 제공 시: URL 모드 (presigned URL 미발급, 즉시 처리)
- 미제공 시: 업로드 모드 (presigned URL 발급)
example: https://example.com/image.jpg
watermarks:
type: array
minItems: 1
maxItems: 10
items:
type: object
required:
- text
properties:
text:
type: string
maxLength: 1000
description: 워터마크 텍스트
examples:
uploadMode:
summary: 업로드 모드 (기본)
value:
idempotencyKey: key-embed-001
files:
- fileName: image1.jpg
watermarks:
- text: MORI_WATERMARK
- fileName: image2.png
watermarks:
- text: MORI_WATERMARK
urlMode:
summary: URL 모드 (즉시 처리)
value:
idempotencyKey: key-embed-url-001
files:
- fileName: image1.jpg
originalFileUrl: https://example.com/image1.jpg
watermarks:
- text: MORI_WATERMARK
- fileName: image2.png
originalFileUrl: https://example.com/image2.png
watermarks:
- text: MORI_WATERMARK
mixedMode:
summary: 혼합 모드
value:
idempotencyKey: key-embed-mixed-001
files:
- fileName: upload-file.jpg
watermarks:
- text: MORI_WATERMARK
- fileName: url-file.png
originalFileUrl: https://example.com/image.png
watermarks:
- text: MORI_WATERMARK
responses:
'200':
description: 주문 생성 성공
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
orderName:
type: string
orderId:
type: string
status:
type: string
enum:
- pending
description: |
주문 상태
- `pending`: 입력 모드에 관계없이 항상 반환
files:
type: array
items:
type: object
description: >-
파일 정보 (모드에 따라 필드가 다릅니다)
- 업로드 모드: fileId, fileName, uploadUrl, fileKey,
fileFormat, fileType
- URL 모드: fileId, fileName, originalFileUrl,
fileKey, fileFormat, fileType
properties:
fileId:
type: integer
fileName:
type: string
uploadUrl:
type: string
format: uri
description: S3 presigned 업로드 URL. 업로드 모드에서만 반환됩니다.
originalFileUrl:
type: string
format: uri
description: 요청에 전달된 공개 이미지 URL. URL 모드에서만 반환됩니다.
fileKey:
type: string
description: S3 오브젝트 키.
fileFormat:
type: string
description: 파일 형식.
enum:
- JPG
- PNG
- WEBP
- BMP
- TIFF
- PDF
fileType:
type: string
description: 파일 유형 분류.
enum:
- IMG
- DOCUMENT
examples:
uploadModeResponse:
summary: 업로드 모드 응답
value:
data:
orderName: wtr_embed_20260318120000.000
orderId: '424706541233094656'
status: pending
files:
- fileId: 2469
fileName: image.jpg
uploadUrl: >-
https://s3.ap-northeast-2.amazonaws.com/...?X-Amz-Algorithm=AWS4-HMAC-SHA256&...
fileKey: wtr-embed/424706541233094656/images/1/image.jpg
fileFormat: JPG
fileType: IMG
- fileId: 2470
fileName: document.pdf
uploadUrl: >-
https://s3.ap-northeast-2.amazonaws.com/...?X-Amz-Algorithm=AWS4-HMAC-SHA256&...
fileKey: >-
wtr-embed/424706541233094656/documents/2/document.pdf
fileFormat: PDF
fileType: DOCUMENT
urlModeResponse:
summary: URL 모드 응답
value:
data:
orderName: wtr_embed_20260318120000.000
orderId: '424707536709206016'
status: pending
files:
- fileId: 2490
fileName: image.png
originalFileUrl: https://example.com/image.jpg
fileKey: wtr-embed/424707536709206016/images/1/image.png
fileFormat: PNG
fileType: IMG
mixedModeResponse:
summary: 혼합 모드 응답
value:
data:
orderName: wtr_embed_20260318120000.000
orderId: '424707536709206016'
status: pending
files:
- fileId: 2490
fileName: image.png
originalFileUrl: https://example.com/image.jpg
fileKey: wtr-embed/424707536709206016/images/1/image.png
fileFormat: PNG
fileType: IMG
- fileId: 2491
fileName: photo.jpeg
uploadUrl: >-
https://s3.ap-northeast-2.amazonaws.com/...?X-Amz-Algorithm=AWS4-HMAC-SHA256&...
fileKey: wtr-embed/424707536709206016/images/2/photo.jpeg
fileFormat: JPG
fileType: IMG
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/UsageLimitExceeded'
security:
- BearerAuth: []
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -X POST https://api.bizmori.com/api/v2/orders/wtr-embed \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "key-embed-001",
"files": [
{
"fileName": "image.jpg",
"watermarks": [{"text": "MORI_WATERMARK"}]
}
]
}'
- lang: javascript
label: JavaScript
source: >-
const response = await
fetch('https://api.bizmori.com/api/v2/orders/wtr-embed', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
idempotencyKey: 'key-embed-001',
files: [
{
fileName: 'image.jpg',
watermarks: [{ text: 'MORI_WATERMARK' }]
}
]
})
});
const data = await response.json();
- lang: python
label: Python
source: |-
import requests
response = requests.post(
'https://api.bizmori.com/api/v2/orders/wtr-embed',
headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
json={
'idempotencyKey': 'key-embed-001',
'files': [
{
'fileName': 'image.jpg',
'watermarks': [{'text': 'MORI_WATERMARK'}]
}
]
}
)
data = response.json()
components:
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
UsageLimitExceeded:
description: 사용량 한도 초과
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: USAGE_LIMIT_EXCEEDED
schemas:
ErrorResponse:
type: object
properties:
code:
type: string
description: 에러 코드
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: 외부 클라이언트 접근을 위한 API 키
````