APIスキャン

APIスキャンは、REST 呼び出しで PDF をリアルなスキャンした文書に変換する機能で、自動処理やアプリ連携に向いています。ジョブを作成し、PDF をアップロードして、ステータスをポーリングするか webhook を待つ——この3ステップで、HTTP リクエストを送れる環境や言語ならどれからでも利用できます。色空間、解像度、回転、ぼかし、ノイズ、明るさ、コントラスト、枠線はすべて指定できます。

呼び出しの流れ

  1. ジョブを作成する

    POST /v1/scan-jobs

    config と、必要なら webhookUrl を送ると、jobID と署名付きの uploadURL が返ります。

  2. PDF をアップロードする

    PUT {uploadURL}

    前の手順で返された署名付き S3 アドレスへ、ファイルをそのまま PUT します。トークンは不要です。

  3. スキャンした文書を受け取る

    GET /v1/scan-jobs/{jobID}

    ステータスをポーリングするか webhook を待ち、completed になったら downloadURL からダウンロードします。

向いている場面

バックエンドでの一括生成

サーバー側で作った契約書・請求書・レポートをそのままスキャン加工に通せるので、誰かがウェブページで同じ作業をやり直す必要がありません。

既存システムへの組み込み

CRM や ERP、チケットシステムに「スキャンした文書を書き出す」操作を追加し、API を呼ばせるだけです。

自動化パイプライン

CI や n8n、Zapier などがイベントを合図にジョブを開始し、完了時に webhook が次の処理へ引き渡します。

大量ファイルの待ち行列

ジョブ方式なので、作成後はそれぞれ非同期に処理され、進捗は status や createdAfter で確認できます。

対応する言語と実行環境

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLコマンドライン / CI
その他任意の HTTP クライアント

API は標準的な HTTP と JSON なので、リクエストを送れる言語や自動化プラットフォームであれば呼び出せます。

コード例

API Bearer Token

トークンはアカウントに紐づき、いつでも再生成できます。APIスキャンには Pro版 のアカウントが必要です。有効なトークンがない場合は 401、Pro版 のロールがない場合は 403 が返ります。

試してみる

パラメーターを調整するとリクエストボディもそのまま変わります。そのうえで3つの呼び出しを順に実行してみてください。

スキャンのパラメーター

試し実行は自分のトークンで API を呼ぶため Pro版 のアカウントが必要です。パラメーターとリクエストボディは自由に確認できます。

POST/v1/scan-jobs
{
  "config": {
    "rotate": 1,
    "rotate_var": 0.5,
    "colorspace": "gray",
    "blur": 0,
    "noise": 0,
    "border": false,
    "brightness": 1.3,
    "contrast": 1.3,
    "resolution": 150,
    "output_format": "image/jpeg"
  }
}

スキャンジョブ情報

{
  "jobID": "3f9c1e64-0000-4000-8000-00000000a71b",
  "userID": "8f21c4b0-0000-4000-8000-000000004a17",
  "createdAt": 1724409600,
  "status": "completed",
  "inputUploadedAt": 1724409601,
  "completedAt": 1724409602,
  "numPages": 6,
  "downloadURL": "https://…/output/3f9c.pdf?X-Amz-…"
}

APIリファレンス

メソッドパス説明
POST/v1/scan-jobsスキャンジョブを作成します。config と、必要なら webhookUrl を送ると、status が created のジョブオブジェクトと署名付き uploadURL が返ります。
PUT{uploadURL}前の手順で返された署名付き S3 アドレス。api.lookscanned.io 上にはありません元の PDF を Content-Type: application/pdf と Content-Length を付けてアップロードします。アドレス自体に署名が含まれるので、Authorization ヘッダーは付けないでください。
GET/v1/scan-jobs/{jobID}単一のジョブを取得します。ポーリング用で、created では uploadURL、completed では downloadURL を含みます。
GET/v1/scan-jobs自分のジョブを一覧します。jobID、status、createdAfter で絞り込めます。
ステータスcreatedprocessingcompletedfailed
  • 401 有効なトークンがない
  • 403 アカウントが Pro版 ではない
  • 404 ジョブが存在しない

リクエストボディ

フィールド既定値説明
webhookUrlstring · —ジョブの完了時に一度呼び出されるので、自分でポーリングする必要がありません。
config.colorspace'gray' | 'sRGB' · graygray出力画像の色空間。gray は白黒のスキャンした文書になります。
config.resolutionnumber · 7272出力画像の解像度(DPI)。
config.rotatenumber · —文書全体の回転角度(度)。
config.rotate_varnumber · —ページごとのランダムな回転の振れ幅(度)。紙を斜めに置いた見た目を再現します。
config.blurnumber · 00ぼかしの強さ。
config.noisenumber · 00ノイズの強さ。
config.brightnessnumber · 11明るさ。1 で変化なし。
config.contrastnumber · 11コントラスト。1 で変化なし。
config.borderboolean · falsefalseページにスキャンの枠線を付けるかどうか。
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegページを画像に描画する際の形式。

すべてのフィールドは省略できます。「試してみる」の初期値(解像度 150、回転 1、明るさとコントラスト 1.3)はウェブ版のおすすめの組み合わせであり、API の既定値ではありません。

ジョブオブジェクトで注目したいフィールド

status
created / processing / completed / failed。下の2つのアドレスが含まれるかどうかを決めます。
uploadURL
created のときだけ返る、有効期限付きの署名付きアップロードアドレス。
downloadURL
completed になったときだけ返る、有効期限付きの署名付きダウンロードアドレス。
inputUploadedAt / completedAt
元ファイルのアップロード完了時刻とジョブの完了時刻。差が処理時間になります。

よくある質問

APIスキャンに Pro版 は必要ですか?

必要です。有効なトークンがなければ 401、Pro版 のロールがないアカウントには 403 が返ります。アップグレードしてログインすれば、このページでトークンを取得できます。

ジョブが終わったことはどう分かりますか?

方法は2つあります。GET /v1/scan-jobs/{jobID} をポーリングするか、ジョブ作成時に webhookUrl を渡し、完了時にサービスから1回通知させます。

結果はウェブページでのスキャンと同じですか?

同じです。どちらも同一のスキャン効果の実装を使っており、config の色空間・解像度・回転・ぼかし・ノイズ・明るさ・コントラスト・枠線はウェブページの同名の設定に対応します。同じパラメーターなら同じ出力になり、違うのは処理する場所だけです——ページ側はローカル、API はリモートのサービスです。

アップロードとダウンロードのアドレスを保存して使い回せますか?

おすすめしません。uploadURL と downloadURL はどちらも有効期限付きの署名付きアドレスで、期限が切れたらジョブを取得し直して新しいものを受け取る必要があります。

ジョブの処理にはどのくらいかかりますか?

ページ数と解像度によります。数ページなら通常は数秒で終わり、解像度が高いほど、ページ数が多いほど時間がかかります。inputUploadedAt と completedAt の差で実際の所要時間を測れます。

ジョブが失敗したらどうすればいいですか?

ステータスが failed になります。よくある原因は、有効な PDF ではないファイル、暗号化による制限、アップロードの中断です。ファイルが開けることを確認したうえで、新しいジョブを作成してください。

過去のジョブは確認できますか?

できます。GET /v1/scan-jobs で自分のジョブを一覧でき、jobID・status・createdAfter で絞り込めるので、照合や再ダウンロードに使えます。