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

事前準備

  • BIZ MORI API キー(こちらから発行)
  • watermark を埋め込む画像または PDF ファイル(jpg、jpeg、png、webp、bmp、tif、tiff、pdf)
自動発行される sk_test_ キーを使うと、実際の watermark 処理を行わず、クレジットも消費せずに v3 のフロー全体を検証できます。テスト注文はアップロードの約 5 秒後に完了し、ダウンロード URL は実際の結果ではなく固定のサンプルファイルを返します。watermark が埋め込まれた実際のファイルが必要な場合は、本番用の API キーを使用してください。

処理の流れ

  1. ファイル名とファイルごとの watermark 文言を指定して注文を作成します。
  2. レスポンスのプリサインド uploadUrl に各ファイルを PUT でアップロードします。すべてのファイルがアップロードされると処理が自動的に始まり、confirm ステップはありません。
  3. GET /api/v3/orders/{orderId} をポーリングするか Webhook を受信して、注文の完了を待ちます。
  4. 結果をダウンロードします。まとめて取得することも、結果ファイルを 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 は注文ファイルが削除される日時です。それまでに結果をダウンロードしてください。
1 つの注文に最大 100 ファイルを含めることができ、画像と PDF を混在させることもできます。すでに公開されているファイルは、アップロードする代わりに originalFileUrl に HTTPS URL を指定できます。BIZ MORI がファイルを直接取得し(最大 32 MiB、リダイレクトは追跡しません)、そのファイルの uploadUrl は null になります。
同じ 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 が返されます。
レスポンス:
結果ファイルを 1 つだけ取得するには、個別ダウンロードのエンドポイントに outputs[].fileId を渡します。
レスポンスの形式は同じです。どちらの URL も 300 秒で期限切れになるため、保存せずにダウンロードのたびに新しくリクエストしてください。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 と同じ形式です。ほとんどの場合、エンドポイントのパスと結果の読み取り方を変えるだけで移行できます。
v3 の watermark 抽出では、v2 で埋め込んだ watermark を検出できません。 エンドポイントを v3 に切り替えるだけでは既存の v2 watermark 画像は検出されず、v2 のサポート終了後に v2 の検出を例外的に受け付けることもありません。
変わらない点:1 つの注文に画像と PDF を混在でき、originalFileUrl を指定すればアップロードを省略でき、confirm を呼び出さずに処理が始まります。
v3 で作成した注文は v3 のエンドポイントで扱ってください。GET /api/v2/orders/{orderId} は v3 注文の共通フィールドだけを返し、outputs は含みません。逆に 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 の抽出

ファイルから watermark を検出し、レポートを作成します。

テスト API キー

クレジットを消費せずに v3 のフローを検証します。

Webhook

処理が完了したら通知を受け取ります。

API リファレンス

v3 watermark 埋め込みエンドポイントのすべてのフィールドを確認します。