API クイックスタート:最初のファイルを変換する
API キーを作成し、ファイルを送信し、ジョブの完了を待って結果をダウンロードするまでの流れを、そのままコピーして使えるリクエスト例で説明します。
要点
ダッシュボード → APIとキー でキーを作成し、公開ファイルの URL、ファイル名、変換先の形式を指定して POST https://maxscanner.app/api/v1/jobs/ を送信します。API はすぐに jobId を返します。status が "completed" になるまで数秒ごとに GET /api/v1/jobs/{jobId}/ をポーリングし、完了したら 5 分以内に output.downloadUrl からダウンロードしてください。
クイックスタート
- 1ダッシュボード → APIとキー を開き、「APIキーを作成」を選んで「ファイルの処理」にチェックを入れ、キーをコピーします(キーは一度しか表示されません)。
- 2キーは MAXSCANNER_API_KEY などの環境変数に保存します。クライアント側のコードには決して含めないでください。
- 3url、filename、format を指定して POST /api/v1/jobs/ を送信します。202 レスポンスの jobId を控えておきます。
- 4status が completed または failed になるまで、2〜10 秒ごとに GET /api/v1/jobs/{jobId}/ を送信します。
- 5output.downloadUrl はすぐにダウンロードしてください。署名付きリンクは 5 分で期限切れになります。
始める前に
すべてのリクエストは https://maxscanner.app/api/v1/ に送信し、キーを Bearer トークンとして付与します。リクエスト URL の末尾にはスラッシュを付けてください。スラッシュのない URL には 308 リダイレクトが返され、ほとんどの HTTP クライアントはこれに従いますが、最初からスラッシュを付ければ往復を 1 回省けます。
無料プランでは 1 日 10 リクエスト、1 か月 100 リクエストまで利用でき、連携の構築とテストには十分です。有料プランでは代わりに月間クレジットを使用し、エンドポイントごとに 0〜3 クレジットを消費します。
- ベース URL:https://maxscanner.app/api/v1/
- ヘッダー:Authorization: Bearer <your key>
- ボディ:Content-Type: application/json を指定した JSON
- ファイル:URL インポートまたは直接アップロードで最大 50 MB
Word ファイルを PDF に変換する
jobs エンドポイントは、入力形式と出力形式から適切なプロセッサーを選択します。公開 URL を渡すと、ジョブ作成時にサーバーがファイルを自らダウンロードします(最大 50 MB、30 秒以内。リダイレクトはたどらないため、最終的なファイルのリンクを指定してください)。非公開のファイルは直接アップロードを使い、代わりに sourceKey を渡してください(「ファイルとアップロード」ガイドを参照)。Idempotency-Key ヘッダーを付けておけば、リクエストを再試行しても 2 つ目のジョブが作成されることはありません。
curl -X POST 'https://maxscanner.app/api/v1/jobs/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: quickstart-0001' \
-d '{ "url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf" }'結果を待つ
ジョブは非同期で処理されるため、大きなファイルのために HTTP 接続を開いたままにする必要はありません。ステータス URL をポーリングし、間隔は約 2 秒から始めて 10 秒まで徐々に延ばします。小さな Office ファイルは通常 20 秒以内に完了しますが、1080p の動画では数分かかることがあります。status が completed になると、output にコンテンツタイプ、バイト単位のサイズ、署名付きの downloadUrl が含まれます。
curl 'https://maxscanner.app/api/v1/jobs/6f0c2a6e-8a1b-4a53-9a0e-2b1f4c9d7e11/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY"次のステップ
処理するファイルが数件を超えるようになったらポーリングを Webhook に切り替え、再試行のルールはジョブのガイドで確認してください。そのうえで、目的に合った機能ガイド(OCR、PDF ツール、画像、メディア、保存済みワークフローの実行)を選びます。
よくある質問
SDK のインストールは必要ですか?
いいえ。API はプレーンな HTTPS と JSON で動作するため、HTTP リクエストを送信できる言語やノーコードツールであれば何でも使えます。コード例のガイドに、Node.js、Python、PHP、cURL の完全なサンプルがあります。
ダウンロードリンクの有効期間はどれくらいですか?
5 分です。期限が切れた場合は、ジョブのステータスを再度取得すると新しいリンクが発行されます。
テストモードはありますか?
テストには無料プランを使ってください。エンドポイントは同じで、各アカウントの上限は 1 日 10 リクエスト、1 か月 100 リクエストです。