メインコンテンツへ移動

次に使うツールを探す

ドキュメント/はじめに/API クイックスタート:最初のファイルを変換する
はじめに

API クイックスタート:最初のファイルを変換する

API キーを作成し、ファイルを送信し、ジョブの完了を待って結果をダウンロードするまでの流れを、そのままコピーして使えるリクエスト例で説明します。

要点

ダッシュボード → APIとキー でキーを作成し、公開ファイルの URL、ファイル名、変換先の形式を指定して POST https://maxscanner.app/api/v1/jobs/ を送信します。API はすぐに jobId を返します。status が "completed" になるまで数秒ごとに GET /api/v1/jobs/{jobId}/ をポーリングし、完了したら 5 分以内に output.downloadUrl からダウンロードしてください。

クイックスタート

  1. 1ダッシュボード → APIとキー を開き、「APIキーを作成」を選んで「ファイルの処理」にチェックを入れ、キーをコピーします(キーは一度しか表示されません)。
  2. 2キーは MAXSCANNER_API_KEY などの環境変数に保存します。クライアント側のコードには決して含めないでください。
  3. 3url、filename、format を指定して POST /api/v1/jobs/ を送信します。202 レスポンスの jobId を控えておきます。
  4. 4status が completed または failed になるまで、2〜10 秒ごとに GET /api/v1/jobs/{jobId}/ を送信します。
  5. 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 リクエストです。

関連ガイド