事前準備
- BIZ MORI API キー(こちらから発行)
- watermark を埋め込んだ元のファイル — watermark が埋め込まれた結果ファイルではなく、watermark の埋め込みで送信したファイルです
- 検査するファイル:
- 元のファイルが画像(
jpg、jpeg、png、webp、bmp、tif、tiff)の場合、検査するファイルも画像です。 - 元のファイルが PDF の場合、検査するファイルは PDF、またはその PDF をキャプチャした PNG・JPEG 画像です。
- 元のファイルが画像(
自動発行される
sk_test_ キーを使うと、実際の watermark 検出を行わず、クレジットも消費せずに v3 のフロー全体を検証できます。テストアップロードはファイルの内容を破棄し、結果は検査するファイルの名前で決まります。_detected を含めば detected、それ以外は not_detected になり、どちらかのファイル名に _fail が含まれると注文は失敗します。処理の流れ
- 元のファイルと検査するファイルの名前を指定して注文を作成します。
- レスポンスのプリサインド URL に2 つのファイルを
PUTでアップロードします。両方のアップロードが終わると検出が自動的に始まり、confirm ステップはありません。 GET /api/v3/orders/{orderId}をポーリングするか Webhook を受信して、結果を確認します。- 必要に応じて、結果の PDF レポートを作成します。
ステップ1: 注文の作成
watermark 抽出注文を作成します。1 つの注文で 1 つのファイルを検査し、1 クレジットを消費します。files には常に 2 つの項目があります。files[0] は元のファイル、files[1] は検査するファイルです。
同じ
idempotencyKey は、同じリクエストを再試行するときだけ再利用してください。その場合は新しい注文を作成せず、既存の注文を返します。同じキーでリクエスト本文が異なる場合は 409 WATERMARK_V2_CONFLICT を返します。ステップ2: 2 つのファイルのアップロード
各ファイルをプリサインドuploadUrl に PUT でアップロードします。ストレージへの直接アップロードなので、Authorization ヘッダーは不要です。
Content-Type ヘッダーには、ファイルの拡張子に合った値を指定してください。プリサインド URL はこのタイプで署名されているため、ほかの値を送るとアップロードは拒否されます。
confirm ステップは必要ありません。 2 つのファイルのアップロードが終わると、検出が自動的に始まります。
本番キーの
uploadUrl は 900 秒で期限切れになります。期限が切れた場合は GET /api/v3/orders/{orderId} を呼び出すと、まだアップロードされていないファイルの新しい uploadUrl を取得できます。注文の作成から 12 時間以内に両方のファイルをアップロードしないと、注文は failed になります。テストキーでは 1 時間有効な https://api.bizmori.com/api/v2/test-uploads/{signedToken} が返されます。認証なしで同じように PUT でき、アップロードしたファイルの内容は破棄されます。ステップ3: 結果の確認
status が complete になるまで注文をポーリングし、result を読み取ってください。ポーリングの代わりに Webhook を設定すると、order.watermarkExtract.completed または order.watermarkExtract.failed を受信できます。
status で注文の完了を確認した後、result.detectionStatus で結果を読み取ってください。
result.watermarkTextは埋め込んだ文言です。結果がdetectedで、自分のアカウントが埋め込み、埋め込み記録がちょうど 1 件のときだけ返されます。それ以外はnullです。result.reportSupportedは、この結果で PDF レポートを作成できるかを示します。PDF をキャプチャした画像を検査した場合はfalseです。processingDelayedがtrueの場合、自動再試行をすべて使い切り、手動での復旧を待っている状態です。注文はinProgressのままなので、ポーリングを続けるか Webhook を待ってください。
Webhook のペイロードは v2 のフィールド名をそのまま使います。
order.watermarkExtract.completed は結果を statusCode で通知し、not_detected の代わりに undetected を使います。watermarkFound と watermarkInfo.text も含まれます。ペイロード全体は Webhook を参照してください。ステップ4: PDF レポートの作成(任意)
result.reportSupported が true の場合、結果の PDF レポートを韓国語(ko-KR)、英語(en-US)、日本語(ja-JP)で作成できます。PDF ファイルのレポートは ko-KR のみ対応しています。レポートは 1 クレジットを消費し、作成に成功した場合にのみ差し引かれます。
レポートをリクエストした後、status が completed になるまでポーリングしてください。
download.url は 300 秒で期限切れになります。保存せずに、レポートをダウンロードするたびに GET /api/v3/orders/{orderId}/reports/{locale} を呼び出し直してください。レポートが failed で failure.retryable が true の場合は、POST エンドポイントを再度呼び出して再試行できます。
テストキーでは、結果が
detected のテスト注文に対してのみレポートを作成できます。リクエストするとすぐに completed と 1 ページのサンプル PDF を返し、クレジットは消費しません。React 完全なサンプル
上記すべてを 1 つのコンポーネントにまとめました:2 つのファイル選択、進捗を表示するアップロード、バックオフ付きポーリング、detectionStatus に基づく結果表示、レポートボタンまでを含みます。React 以外の依存関係はありません。
WatermarkExtractChecker.jsx
import.meta.env.VITE_MORI_API_KEY は Vite の構文です。Next.js では process.env.NEXT_PUBLIC_MORI_API_KEY を、その他のバンドラーではクライアントコードに公開する方法を使用してください。crypto.randomUUID() にはセキュアコンテキストが必要です。HTTPS と localhost では動作しますが、通常の HTTP でアクセスする LAN アドレスでは動作しません。detectionStatus、reportSupported、watermarkText のみが含まれ、watermark ID(MID)は含まれません。
エラー処理
エラーコードの一覧は、エラーコード ページを参照してください。
v2 から v3 への移行
v3 では検査するファイルを常に元のファイルと比較するため、リクエストで両方のファイルを指定します。
v2 のサポート終了後の動作(2026 年 10 月 9 日 09:00 KST、00:00 UTC から):
- 認証・権限の確認はこれまでどおり先に行われるため、
401・403エラーは従来と同じです。 - 認証を通過した v2 の watermark 埋め込み・抽出リクエストには、本番キーと
sk_test_キーのどちらでも410 Goneと{ "code": "WATERMARK_V2_API_SUNSET" }が返されます。Linkヘッダーが v3 エンドポイントを示すので、v3 で新しくリクエストしてください。 - その時点までに処理が始まっていない v2 注文は、処理されずに失敗として確定します。注文の詳細(
errors.errorCode)と失敗 Webhook にはWATERMARK_V2_API_SUNSETと v3 への案内メッセージが含まれ、課金されずクレジットは戻ります。 - 終了時点ですでに処理中の注文は、結果の記録まで完了します。その後に改めて実行されることはありません。
- 既存の v2 注文の取得と、作成済みの結果・レポートのダウンロードは、既存の保管期間内であれば引き続き利用できます。v2 レポートの新規作成・再作成はできません。
Deprecation: true、Sunset: Fri, 09 Oct 2026 00:00:00 GMT、Link ヘッダーが付くだけです。
次のステップ
不可視 watermark の埋め込み
画像と PDF に不可視 watermark を埋め込みます。
テスト API キー
クレジットを消費せずに v3 のフローを検証します。
Webhook
検出が完了したら通知を受け取ります。
API リファレンス
v3 watermark 抽出エンドポイントのすべてのフィールドを確認します。