事前準備
- BIZ MORI API キー(こちらから発行)
- watermark を埋め込む画像または PDF ファイル(
jpg、jpeg、png、webp、bmp、tif、tiff、pdf)
自動発行される
sk_test_ キーを使うと、実際の watermark 処理を行わず、クレジットも消費せずに v3 のフロー全体を検証できます。テスト注文はアップロードの約 5 秒後に完了し、ダウンロード URL は実際の結果ではなく固定のサンプルファイルを返します。watermark が埋め込まれた実際のファイルが必要な場合は、本番用の API キーを使用してください。処理の流れ
- ファイル名とファイルごとの watermark 文言を指定して注文を作成します。
- レスポンスのプリサインド
uploadUrlに各ファイルをPUTでアップロードします。すべてのファイルがアップロードされると処理が自動的に始まり、confirm ステップはありません。 GET /api/v3/orders/{orderId}をポーリングするか Webhook を受信して、注文の完了を待ちます。- 結果をダウンロードします。まとめて取得することも、結果ファイルを 1 つずつ取得することもできます。
ステップ1: 注文の作成
watermark 埋め込み注文を作成します。各ファイルには watermark 文言を 1〜10 個指定でき、文言 1 つごとに結果ファイルが 1 つ作成され、1 クレジットを消費します。次のリクエストは 1 枚の画像に 2 つの文言を埋め込むため、結果ファイルが 2 つ作成され、2 クレジットを消費します。files[]はリクエストのfilesと同じ順序で返されます。リクエストのfiles[i]のファイルはfiles[i].uploadUrlにアップロードしてください。outputs[]には watermark 文言ごとに 1 件ずつ項目があります。結果ファイルを 1 つずつダウンロードする場合はoutputs[].fileIdを保持しておいてください。expiresAtは注文ファイルが削除される日時です。それまでに結果をダウンロードしてください。
同じ
idempotencyKey は、同じリクエストを再試行するときだけ再利用してください。その場合は新しい注文を作成せず、既存の注文を返します。同じキーでリクエスト本文が異なる場合は 409 WATERMARK_V2_CONFLICT を返します。ステップ2: ファイルのアップロード
各ファイルをプリサインドuploadUrl に PUT でアップロードします。ストレージへの直接アップロードなので、Authorization ヘッダーは不要です。
Content-Type ヘッダーには、ファイルの拡張子に合った値を指定してください。プリサインド URL はこのタイプで署名されているため、ほかの値を送るとアップロードは拒否されます。
confirm ステップは必要ありません。 注文のすべてのファイルがアップロードされると、処理が自動的に始まります。
本番キーの
uploadUrl は 900 秒で期限切れになります。期限が切れた場合は GET /api/v3/orders/{orderId} を呼び出すと、まだアップロードされていないファイルの新しい uploadUrl を取得できます。注文の作成から 12 時間以内にすべてのファイルをアップロードしないと、注文は failed になります。テストキーでは 1 時間有効な https://api.bizmori.com/api/v2/test-uploads/{signedToken} が返されます。認証なしで同じように PUT でき、アップロードしたファイルの内容は破棄されます。ステップ3: 注文の完了を待つ
status が complete になるまで注文をポーリングしてください。ポーリングの代わりに Webhook を設定すると、order.watermarkEmbed.completed または order.watermarkEmbed.failed を受信できます。
processingDelayed が true の場合、自動再試行をすべて使い切り、手動での復旧を待っている状態です。注文は inProgress のままなので、ポーリングを続けるか Webhook を待ってください。
order.watermarkEmbed.failed Webhook には、失敗の原因を示す errorCode が含まれます。イベントのペイロードとエラーコードは Webhook を参照してください。
ステップ4: 結果のダウンロード
status が complete になったら、注文全体のダウンロード URL をリクエストします。結果ファイルが 1 つならそのファイル、複数なら ZIP ファイルを指す URL が返されます。
outputs[].fileId を渡します。
expiresAt を過ぎると、どちらのエンドポイントも 400 ORDER_EXPIRED を返します。
テスト注文では、これらのエンドポイントは固定のサンプルファイルの URL を返します(結果が複数ある場合は ZIP)。実際に watermark が埋め込まれたファイルではありません。
React 完全なサンプル
上記すべてを 1 つのコンポーネントにまとめました:進捗を表示する単一ファイルのアップロード、追加・削除と重複チェックが可能な watermark 文言のリスト、バックオフ付きポーリング、押すたびに新しい URL を取得するダウンロードボタンまでを含みます。React 以外の依存関係はありません。WatermarkEmbedUploader.jsx
import.meta.env.VITE_MORI_API_KEY は Vite の構文です。Next.js では process.env.NEXT_PUBLIC_MORI_API_KEY を、その他のバンドラーではクライアントコードに公開する方法を使用してください。crypto.randomUUID() にはセキュアコンテキストが必要です。HTTPS と localhost では動作しますが、通常の HTTP でアクセスする LAN アドレスでは動作しません。エラー処理
エラーコードの一覧は、エラーコード ページを参照してください。
v2 から v3 への移行
v3 のリクエスト本文は v2 と同じ形式です。ほとんどの場合、エンドポイントのパスと結果の読み取り方を変えるだけで移行できます。
変わらない点:1 つの注文に画像と PDF を混在でき、
originalFileUrl を指定すればアップロードを省略でき、confirm を呼び出さずに処理が始まります。
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 の抽出
ファイルから watermark を検出し、レポートを作成します。
テスト API キー
クレジットを消費せずに v3 のフローを検証します。
Webhook
処理が完了したら通知を受け取ります。
API リファレンス
v3 watermark 埋め込みエンドポイントのすべてのフィールドを確認します。