Watermark Embed

This guide walks you through embedding an invisible watermark into an image — from creating an order to downloading the watermarked result. Every endpoint here is plain HTTPS and JSON, so the same calls work from a server or straight from the browser. Each step includes a React tab, and a full copy-paste component is at the bottom of the page.

Prerequisites

A BIZ MORI API key (get one here)
An image or PDF file to watermark (jpeg, jpg, png, webp, tiff, bmp, or pdf)

Use the automatically issued sk_test_ key to exercise the order lifecycle without running watermark processing or consuming credits. Test uploads discard file contents and do not produce a downloadable result. Use a live API key when you need an actual watermarked file.

Step 1: Create an order

Create a watermark embed order with your watermark text.

ORDER_IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')
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": "'$ORDER_IDEMPOTENCY_KEY'",
    "files": [
      {
        "fileName": "photo.jpg",
        "watermarks": [{ "text": "MORI_WATERMARK" }]
      }
    ]
  }'

import { randomUUID } from 'node:crypto';

const orderIdempotencyKey = randomUUID();
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: orderIdempotencyKey,
    files: [
      {
        fileName: 'photo.jpg',
        watermarks: [{ text: 'MORI_WATERMARK' }],
      },
    ],
  }),
});
const { data } = await response.json();

// One helper for every JSON call. The API returns `{ code: "ERROR_CODE" }`
// on failure, so surface that code instead of a bare status number.
const API_BASE = 'https://api.bizmori.com/api/v2';
const API_TOKEN = import.meta.env.VITE_MORI_API_TOKEN;

async function api(path, { method = 'GET', body, idempotencyKey } = {}) {
  const res = await fetch(`${API_BASE}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${API_TOKEN}`,
      ...(body && { 'Content-Type': 'application/json' }),
    },
    body: body && JSON.stringify({ idempotencyKey, ...body }),
  });

  if (!res.ok) {
    const { code } = await res.json().catch(() => ({}));
    throw new Error(code ?? `HTTP_${res.status}`);
  }
  return (await res.json()).data;
}

// `file` is the single File the user picked, `watermarkTexts` is a string[]
const order = await api('/orders/wtr-embed', {
  method: 'POST',
  idempotencyKey: crypto.randomUUID(),
  body: {
    files: [
      {
        fileName: file.name,
        watermarks: watermarkTexts.map((text) => ({ text })),
      },
    ],
  },
});

import uuid
import requests

order_idempotency_key = str(uuid.uuid4())
res = requests.post(
    'https://api.bizmori.com/api/v2/orders/wtr-embed',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    json={
        'idempotencyKey': order_idempotency_key,
        'files': [
            {
                'fileName': 'photo.jpg',
                'watermarks': [{'text': 'MORI_WATERMARK'}],
            }
        ],
    },
)
data = res.json()['data']

Response:

{
  "data": {
    "orderName": "wtr_embed_2026-03-18",
    "orderId": "123456789",
    "status": "pending",
    "files": [
      {
        "fileId": 1,
        "fileName": "photo.jpg",
        "uploadUrl": "https://s3.amazonaws.com/...",
        "fileKey": "wtr-embed/123456789/images/1/photo.jpg",
        "fileFormat": "JPG",
        "fileType": "IMG"
      }
    ]
  }
}

Step 2: Upload files

PUT your file to the presigned uploadUrl from Step 1. This is a direct S3 upload — no Authorization header needed.

curl -X PUT "https://s3.amazonaws.com/..." \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

// fetch() cannot report upload progress, so use XMLHttpRequest for the PUT.
function putFile(file, uploadUrl, onProgress) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open('PUT', uploadUrl);
    xhr.setRequestHeader('Content-Type', file.type);

    xhr.upload.onprogress = (event) => {
      if (event.lengthComputable) onProgress(event.loaded / event.total);
    };
    xhr.onload = () =>
      xhr.status < 300 ? resolve() : reject(new Error(`UPLOAD_FAILED_${xhr.status}`));
    xhr.onerror = () => reject(new Error('UPLOAD_NETWORK_ERROR'));

    xhr.send(file);
  });
}

// There's exactly one file, so upload progress is a single number.
await putFile(file, order.files[0].uploadUrl, (ratio) => setProgress(ratio));

No confirm step needed. Unlike Anti-AI and AI Detection, Watermark Embed processing starts automatically after your file upload completes. Proceed directly to checking the order status.

Live keys receive S3 presigned URLs. Test keys receive https://api.bizmori.com/api/v2/test-uploads/{signedToken}; both expire after 1 hour and accept the same unauthenticated PUT. Test uploads are streamed only, not stored or processed. Use Refresh URLs if a URL expires.

Step 3: Check order status & download result

Poll the order or use webhooks to receive a push notification when processing completes.

curl https://api.bizmori.com/api/v2/orders/123456789 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch('https://api.bizmori.com/api/v2/orders/123456789', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' },
});
const { data } = await res.json();
// data.status: 'pending' | 'inProgress' | 'complete' | 'failed'

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Back off as the wait grows: quick answers stay quick, long jobs stop
// hammering the API. Give up after 10 minutes rather than polling forever.
async function pollOrder(orderId, { onStatus, timeoutMs = 10 * 60 * 1000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  let delay = 2000;

  while (Date.now() < deadline) {
    const order = await api(`/orders/${orderId}`);
    onStatus?.(order.status);
    if (['complete', 'failed', 'expired'].includes(order.status)) return order;

    await sleep(delay);
    delay = Math.min(delay * 1.5, 15000);
  }
  throw new Error('ORDER_POLL_TIMEOUT');
}

res = requests.get(
    'https://api.bizmori.com/api/v2/orders/123456789',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
)
status = res.json()['data']['status']

Status	Meaning
`pending`	Waiting for file upload
`inProgress`	Processing
`complete`	Ready for download
`failed`	Processing failed

Once status is complete, fetch the download URL:

curl https://api.bizmori.com/api/v2/orders/123456789/download \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const res = await fetch('https://api.bizmori.com/api/v2/orders/123456789/download', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' },
});
const { data } = await res.json();
// data.url — valid for 7 days

const { url } = await api(`/orders/${order.orderId}/download`);
// Hand it to an <a href={url} download> — the URL is valid for 7 days
setDownloadUrl(url);

res = requests.get(
    'https://api.bizmori.com/api/v2/orders/123456789/download',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
)
download_url = res.json()['data']['url']

Response:

{
  "data": {
    "url": "https://s3.amazonaws.com/..."
  }
}

The url is a presigned S3 URL valid for 7 days.

Full React example

Everything above, wired into one component: single-file upload with progress, a watermark text list with add/remove and duplicate detection, backoff polling, and a download link. No dependencies beyond React.

WatermarkEmbedUploader.jsx

import { useMemo, useRef, useState } from 'react';

const API_BASE = 'https://api.bizmori.com/api/v2';
const API_TOKEN = import.meta.env.VITE_MORI_API_TOKEN;

const ACCEPT_FORMATS = '.jpg,.jpeg,.png,.webp,.tiff,.bmp,.pdf';
const MAX_WATERMARKS = 10;
const MAX_TEXT_LENGTH = 1000;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function api(path, { method = 'GET', body, idempotencyKey } = {}) {
  // Retries reuse the caller's idempotency key, so a retried create can never
  // produce a second order. Auth failures surface as `AUTH_*` codes — retrying
  // those will not help, so they fall through to the throw below.
  for (let attempt = 0; ; attempt++) {
    const res = await fetch(`${API_BASE}${path}`, {
      method,
      headers: {
        Authorization: `Bearer ${API_TOKEN}`,
        ...(body && { 'Content-Type': 'application/json' }),
      },
      body: body && JSON.stringify({ idempotencyKey, ...body }),
    });

    if (!res.ok) {
      const { code } = await res.json().catch(() => ({}));
      // 429 covers two cases: a transient rate limit, and PLAN_LIMIT_EXCEEDED,
      // which means the plan quota is spent and will never clear on retry.
      if (res.status === 429 && code !== 'PLAN_LIMIT_EXCEEDED' && attempt < 3) {
        await sleep(2 ** attempt * 1000);
        continue;
      }
      throw new Error(code ?? `HTTP_${res.status}`);
    }
    return (await res.json()).data;
  }
}

function putFile(file, uploadUrl, onProgress) {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open('PUT', uploadUrl);
    xhr.setRequestHeader('Content-Type', file.type);

    xhr.upload.onprogress = (event) => {
      if (event.lengthComputable) onProgress(event.loaded / event.total);
    };
    xhr.onload = () =>
      xhr.status < 300 ? resolve() : reject(new Error(`UPLOAD_FAILED_${xhr.status}`));
    xhr.onerror = () => reject(new Error('UPLOAD_NETWORK_ERROR'));

    xhr.send(file);
  });
}


async function pollOrder(orderId, { onStatus, timeoutMs = 10 * 60 * 1000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  let delay = 2000;

  while (Date.now() < deadline) {
    const order = await api(`/orders/${orderId}`);
    onStatus?.(order.status);
    if (['complete', 'failed', 'expired'].includes(order.status)) return order;

    await sleep(delay);
    delay = Math.min(delay * 1.5, 15000);
  }
  throw new Error('ORDER_POLL_TIMEOUT');
}

export default function WatermarkEmbedUploader() {
  const [file, setFile] = useState(null);
  // Lazy initializer: without it, crypto.randomUUID() would run on every render.
  const [watermarks, setWatermarks] = useState(() => [{ id: crypto.randomUUID(), text: '' }]);
  const [progress, setProgress] = useState(0);
  const [status, setStatus] = useState('idle');
  const [downloadUrl, setDownloadUrl] = useState(null);
  const [error, setError] = useState(null);
  const [orderId, setOrderId] = useState(null);
  const inFlight = useRef(false);

  const busy = status !== 'idle' && status !== 'complete';

  // Flags every text after the first occurrence as a duplicate. Blank rows
  // are exempt — they're already caught by the "no blank text" rule below.
  const duplicateIds = useMemo(() => {
    const seen = new Map();
    const duplicates = new Set();
    watermarks.forEach((watermark) => {
      const text = watermark.text.trim();
      if (text === '') return;
      if (seen.has(text)) duplicates.add(watermark.id);
      else seen.set(text, watermark.id);
    });
    return duplicates;
  }, [watermarks]);

  const canSubmit =
    file !== null &&
    watermarks.length > 0 &&
    watermarks.every((watermark) => watermark.text.trim() !== '') &&
    duplicateIds.size === 0 &&
    !busy;

  function updateWatermark(id, text) {
    setWatermarks((prev) => prev.map((watermark) => (watermark.id === id ? { ...watermark, text } : watermark)));
  }

  function addWatermark() {
    if (watermarks.length >= MAX_WATERMARKS) return;
    setWatermarks((prev) => [...prev, { id: crypto.randomUUID(), text: '' }]);
  }

  function removeWatermark(id) {
    setWatermarks((prev) => prev.filter((watermark) => watermark.id !== id));
  }

  async function embedWatermarks(event) {
    event.preventDefault();
    if (inFlight.current || !canSubmit) return;
    inFlight.current = true;

    // Snapshot the selection. The user can edit the form while requests are
    // in flight, and the upload must use the values as they were on submit.
    const selectedFile = file;
    const selectedWatermarks = watermarks;
    setError(null);
    setOrderId(null);
    setDownloadUrl(null);
    setProgress(0);

    try {
      setStatus('creating order');
      const order = await api('/orders/wtr-embed', {
        method: 'POST',
        idempotencyKey: crypto.randomUUID(),
        body: {
          files: [
            {
              fileName: selectedFile.name,
              watermarks: selectedWatermarks.map((watermark) => ({ text: watermark.text.trim() })),
            },
          ],
        },
      });

      setOrderId(order.orderId);
      setStatus('uploading');
      await putFile(selectedFile, order.files[0].uploadUrl, setProgress);

      // No confirm step — processing starts automatically once the upload completes.
      const finished = await pollOrder(order.orderId, { onStatus: setStatus });
      // `expired` is terminal too: the cleanup job drops the files after 7 days.
      if (finished.status !== 'complete') throw new Error(`ORDER_${finished.status.toUpperCase()}`);

      setStatus('fetching download URL');
      const { url } = await api(`/orders/${order.orderId}/download`);
      setDownloadUrl(url);
      setStatus('complete');
    } catch (caught) {
      setError(caught.message);
      setStatus('idle');
    } finally {
      inFlight.current = false;
    }
  }

  return (
    <form onSubmit={embedWatermarks}>
      <input
        type="file"
        accept={ACCEPT_FORMATS}
        disabled={busy}
        onChange={(event) => {
          setFile(event.target.files[0] ?? null);
          setError(null);
          setProgress(0);
          setDownloadUrl(null);
        }}
      />

      <ul>
        {watermarks.map((watermark, index) => (
          <li key={watermark.id}>
            <input
              type="text"
              value={watermark.text}
              maxLength={MAX_TEXT_LENGTH}
              disabled={busy}
              placeholder={`Watermark text #${index + 1}`}
              onChange={(event) => updateWatermark(watermark.id, event.target.value)}
              style={{ borderColor: duplicateIds.has(watermark.id) ? 'red' : undefined }}
            />
            <button type="button" disabled={busy || watermarks.length === 1} onClick={() => removeWatermark(watermark.id)}>
              Remove
            </button>
          </li>
        ))}
      </ul>
      <button type="button" disabled={busy || watermarks.length >= MAX_WATERMARKS} onClick={addWatermark}>
        Add watermark text ({watermarks.length}/{MAX_WATERMARKS})
      </button>

      <button type="submit" disabled={!canSubmit}>
        Embed watermark{watermarks.length === 1 ? '' : 's'}
      </button>

      {status !== 'idle' && <p>Status: {status}</p>}
      {status === 'uploading' && <p>Upload progress: {Math.round(progress * 100)}%</p>}

      {downloadUrl && (
        <a href={downloadUrl} download>
          Download watermarked image
        </a>
      )}
      {error && <p role="alert">Failed: {error}{orderId && ` (orderId: ${orderId})`}</p>}
    </form>
  );
}

import.meta.env.VITE_MORI_API_TOKEN is Vite’s syntax. Use process.env.NEXT_PUBLIC_MORI_API_TOKEN on Next.js, or whatever your bundler exposes to client code. crypto.randomUUID() needs a secure context: HTTPS and localhost are fine, a plain-HTTP LAN address is not.

Test orders do not produce a result file: their downloadUrl is null, and the download endpoint can return PROCESSED_FILE_NOT_FOUND.

Error handling

HTTP Status	Meaning	Action
`400`	Invalid request	Check parameters and file format
`401`	Authentication failed	Verify your API key
`429`	Rate limit, or `PLAN_LIMIT_EXCEEDED` when the plan quota is spent	Check the `code` field. A rate limit clears on retry; `PLAN_LIMIT_EXCEEDED` does not — upgrade the plan

For the complete error code reference, see Error Codes.

Next steps

Anti-AI

Protect images from AI training and generation.

Watermark Extract

Detect and extract watermarks from images.

AI Detection

Detect AI-generated images with probability scores.

Webhooks

Set up webhooks to get notified when processing completes.

Getting Started

Use Without Code

Build with AI Agents

Guides

Prerequisites

Step 1: Create an order

Step 2: Upload files

Step 3: Check order status & download result

Full React example

Error handling

Next steps

Anti-AI

Watermark Extract

AI Detection

Webhooks

​Prerequisites

​Step 1: Create an order

​Step 2: Upload files

​Step 3: Check order status & download result

​Full React example

​Error handling

​Next steps

Anti-AI

Watermark Extract

AI Detection

Webhooks

Prerequisites

Step 1: Create an order

Step 2: Upload files

Step 3: Check order status & download result

Full React example

Error handling

Next steps