Skip to main content
このガイドでは、v3 API でファイルに不可視 watermark が含まれているかを確認する手順を、注文の作成から結果の確認、PDF レポートのダウンロードまで説明します。 すべてのエンドポイントは純粋な HTTPS と JSON を使用するため、サーバーからでもブラウザからでも同じように呼び出せます。各ステップには React タブがあり、そのままコピーして使える完全なコンポーネントはページ下部にあります。
v2 の watermark 抽出エンドポイント(POST /api/v2/orders/wtr-extract)は 2026 年 10 月 9 日 09:00 KST(00:00 UTC)にサポートを終了する予定です。このガイドは v3 API を前提に説明します。すでに v2 を使用している場合は、v2 から v3 への移行を参照してください。
v3 の watermark 抽出では、v2 で埋め込んだ watermark を検出できません。 エンドポイントを v3 に切り替えるだけでは既存の v2 watermark 画像は検出されず、v2 のサポート終了後に v2 の検出を例外的に受け付けることもありません。

事前準備

  • 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 が含まれると注文は失敗します。

処理の流れ

  1. 元のファイルと検査するファイルの名前を指定して注文を作成します。
  2. レスポンスのプリサインド URL に2 つのファイルを PUT でアップロードします。両方のアップロードが終わると検出が自動的に始まり、confirm ステップはありません。
  3. GET /api/v3/orders/{orderId} をポーリングするか Webhook を受信して、結果を確認します。
  4. 必要に応じて、結果の 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 を受信できます。
レスポンス(watermark が検出された場合):
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 では検査するファイルを常に元のファイルと比較するため、リクエストで両方のファイルを指定します。
v3 の watermark 抽出では、v2 で埋め込んだ watermark を検出できません。 エンドポイントを v3 に切り替えるだけでは既存の v2 watermark 画像は検出されず、v2 のサポート終了後に v2 の検出を例外的に受け付けることもありません。
v3 で作成した注文は v3 のエンドポイントで扱ってください。GET /api/v2/orders/{orderId} は v3 注文の共通フィールドだけを返し、result は含みません。逆に GET /api/v3/orders/{orderId} は v2 の注文に対して 404 ORDER_NOT_FOUND を返します。
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 抽出エンドポイントのすべてのフィールドを確認します。