結論から言うと、SmartSlim ServerはRESTful APIを提供しており、アップロード圧縮・一括圧縮・状態照会・コールバック通知の4つの主にインターフェースを含み、API KeyとBearer Tokenの2つの認証方法に対応しています。100MBのPDFを単一ファイルとしてアップロード圧縮た場合、約8秒で完します。100ファイルの一括圧縮は約12秒です。デフォルトのレート制限は1分あたり60リクエスト、エンタープライズ版では300リクエストまで引き上げ可能性です。本記事では、4つのインターフェースのパラメータ仕様表、Python／JavaScript／curlによる呼び出し例、エラーハンドリング方法を紹介します。API概要から順に、各インターフェースを解説します。
HTTP API呼び出しではなくSDKでローカル統合したい場合は、まず圧縮SDK統合ガイド：Python／Java／C#の多言語呼び出しをご覧ください。
1. APIインターフェース概要
SmartSlim ServerのRESTful APIはFastAPIフレームワークをベースに開発されており、すべてのインターフェースはJSON形式データを返し、multipart/form-dataでのファイルアップロードに対応しています。APIのベースパスは/api/v1/で、すべてのリクエストに認証情報の付とが必要です。
| インターフェース | メソッド | パス | 機能 | 同期／非同期 |
|---|---|---|---|---|
| アップロード圧縮 | POST | /api/v1/compress | 単一ファイルをアップロードして圧縮 | 同期（50MB以下）／非同期 |
| 一括圧縮 | POST | /api/v1/compress/batch | 複数ファイルを一括アップロードして圧縮 | 非同期 |
| 状態照会 | GET | /api/v1/status/{task_id} | 圧縮タスクの状態を照会 | 同期 |
| コールバック通知 | POST | クライアントのコールバックURL | 圧縮完時に能動的に通知 | 非同期プッシュ |
認証方法は2種類あります。API Key認証はサーバー側からの呼び出しに適し、Bearer Token認証はフロントエンドからの呼び出しに適しています。下表で2つの認証方法の特徴を比較します。
| 認証方法 | リクエストヘッダー | 有効期間 | 適用シーン | セキュリティ |
|---|---|---|---|---|
| API Key | X-API-Key: your-key | 永続（失効可能性） | サーバー側からの呼び出し | 中（HTTPS必須） |
| Bearer Token | Authorization: Bearer token | 24時間 | フロントエンドからの呼び出し | 高（短期有効） |
2. 各インターフェースのパラメータ仕様
2.1 アップロード圧縮インターフェース
アップロード圧縮インターフェースは単一のファイルを受け取り、圧縮結果を返します。50MB以下のファイルは同期のに圧縮後のダウンロードリンクを返し、50MB超のファイルは非同期でタスクIDを返します。
| パラメータ | 型 | 必須 | デフォルト値 | 説明 |
|---|---|---|---|---|
| file | multipart/file | 必須 | - | 圧縮対象のファイル |
| format | string | 任意 | 自動検出 | ファイル形式（pdf/image/ofd） |
| level | string | 任意 | medium | 圧縮レベル（low/medium/high/ultra） |
| quality | integer | 任意 | 75 | 品質係数（1〜100） |
| callback_url | string | 任意 | - | 非同期コールバック通知URL |
2.2 一括圧縮インターフェース
一括圧縮インターフェースは複数ファイルを受け取り、非同期で処理して一括タスクIDを返します。同時実行数を指定でき、上限はライセンスにより異なります。
| パラメータ | 型 | 必須 | デフォルト値 | 説明 |
|---|---|---|---|---|
| files | multipart/file[] | 必須 | - | 圧縮対象ファイル一覧（最大100件） |
| level | string | 任意 | medium | 圧縮レベル |
| quality | integer | 任意 | 75 | 品質係数 |
| workers | integer | 任意 | 4 | 同時実行数（1〜16） |
| callback_url | string | 任意 | - | 完時のコールバックURL |
2.3 状態照会インターフェース
状態照会インターフェースは、タスクIDを使って非同期圧縮タスクの現において状態と結果を取得します。
| 返却フィールド | 型 | 説明 |
|---|---|---|
| task_id | string | タスクの一意な識別子 |
| status | string | 状態（pending/processing/completed/failed） |
| progress | integer | 進捗率（0〜100） |
| download_url | string | 圧縮結果のダウンロードリンク（完後） |
| original_size | integer | 元ファイルのサイズ（バイト） |
| compressed_size | integer | 圧縮後のサイズ（バイト） |
| error | string | エラー情報（失敗時） |
3. 3言語での呼び出し例
以下ではcurl、Python、JavaScriptの3言語での呼び出し例を示します。いずれも単一のPDFフォントァイルをアップロード圧縮する例です。
| 言語 | コアコード | 説明 |
|---|---|---|
| curl | curl -X POST -H "X-API-Key: key" -F "file=@doc.pdf" -F "level=medium" http://localhost:8000/api/v1/compress | コマンドライン呼び出し |
| Python | requests.post(url, headers={"X-API-Key":key}, files={"file":open("doc.pdf","rb")}, data={"level":"medium"}) | requestsライブラリ |
| JavaScript | fetch(url, {method:"POST", headers:{"X-API-Key":key}, body:formData}) | Fetch API |
4. レート制限とエラーハンドリング
APIにはレート制限とエラーハンドリングの機構が備わっています。HTTPステータスコードとエラーコードを理解することで、堅牢な呼び出しコードが書けます。
| HTTPステータスコード | エラーコード | 意味 | 対処の目安 |
|---|---|---|---|
| 200 | - | 成功 | レスポンスデータを解析 |
| 400 | INVALID_PARAM | パラメータエラー | リクエストパラメータを確認 |
| 401 | UNAUTHORIZED | 認証失敗 | API Key／Tokenを確認 |
| 413 | FILE_TOO_LARGE | ファイファイルサイズ超過 | 分割アップロードを利用 |
| 429 | RATE_LIMITED | リクエスト過多 | 指数バックオフで再試行 |
| 500 | INTERNAL_ERROR | サーバーエラー | 再試行またはサポートに連絡 |
| 503 | SERVICE_UNAVAILABLE | サービス利用不可 | 待機後に再試行 |
レート制限の詳細：デフォルトでは1分あたり60リクエスト、1秒あたり10同時実行、エンタープライズ版では1分あたり300リクエスト、1秒あたり30同時実行です。上限を超えると429が返され、レスポンスヘッダーにはX-RateLimit-Remaining（残り回数）とX-RateLimit-Reset（リセット時刻のタイムスタンプ）が含まれます。クライアント側での指数バックオフ再試行の実装を推奨します。429受信時は1秒待機して再試行、続けて失敗したら2秒、さらに失敗したら4秒と待ち時間を延ばし、最大3回まで再試行します。
| ファイル形式 | 元のサイズ | 圧縮後のサイズ | 圧縮時間 | 圧縮率 |
|---|---|---|---|---|
| PDF（スキャン） | 80MB | 8.2MB | 6.5秒 | 89.8% |
| PDF（電子） | 15MB | 3.1MB | 1.2秒 | 79.3% |
| JPEG画像 | 12MB | 2.8MB | 0.8秒 | 76.7% |
| PNG画像 | 25MB | 6.5MB | 1.5秒 | 74.0% |
| OFD文書 | 30MB | 5.2MB | 2.0秒 | 82.7% |
圧縮タスクキューューのバックエンド設計を理解したい場合は、圧縮タスクキューューの設計をご参照ください。DockerでAPIサービスをデプロイする場合は、Dockerで圧縮サービスをデプロイするをご参照ください。
5. よくある質問（FAQ）
Q1：圧縮APIの認証方法はどうすればよいですか？
SmartSlim Serverの圧縮APIは2つの認証方法をサポートしています。1つはAPI Key認証（リクエストヘッダーのX-API-Keyにキーを設定。サーバー側からの呼び出しに適しています）、もう1つはBearer Token認証（AuthorizationヘッダーにJWT Tokenを設定。フロントエンドからの呼び出しに適しています）。API Keyは永続のに有効ですがいつでも失効でき、Tokenの有効期限は24時間で定期的に更新が必要です。本番環境ではAPI Key方法を推奨します。シンプルで信頼性が高いためです。
Q2：圧縮APIはどのファイル形式に対応していますか？
SmartSlimサーバー版のAPIはPDF、画像（jpg/jpeg/tif）、OFD形式に対応し、1ファイルあたり上限1GBです。SmartSlimネットワーク版のAPIは10ジャンル40以上の全形式（動画、音声、Office文書などを含む）に対応し、1ファイルあたり上限10GBです。呼び出し時はformatパラメータでファイル形式を指定します。未指定の場合は自動検出されます。なお、サーバー版はPDF／画像／OFDの3形式のみ対応しており、全形式を使うにはネットワーク版が必要です。
Q3：圧縮APIに呼び出し頻度の制限はありますか？
サービスの安定性を守るためレート制限があります。デフォルトでは1分あたり60リクエスト、1秒あたり10同時実行です。上限を超えるとステータスコード429が返され、レスポンスヘッダーにはX-RateLimit-RemainingとX-RateLimit-Resetフィールドが含まれます。エンタープライズ版では1分あたり300リクエスト、1秒あたり30同時実行まで引き上げ可能性です。クライアント側で指数バックオフによる再試行機構を実装し、429受信時は1秒・2秒・4秒と間隔を延ばしなながら再試行することをおすすめします。
Q4：圧縮APIで大ファイルを扱うにはどうすればよいですか？
大きなファイル（50MB超）は分割アップロードインターフェースの利用を推奨します。ファイルを複数の5MBチャンクに分けてアップロードし、すべて完したら結合・圧縮を通知します。圧縮完後はコールバック通知または状態照会インターフェースのポーリングで結果を取得します。大容量ファイルの圧縮は非同期で実行され、API呼び出しをブロックしません。100MBのPDF圧縮は約8秒、1GBの動画圧縮は約90秒で、完するとダウンロードリンクが自動生成されます。
まとめ
SmartSlim ServerのRESTful APIは、アップロード圧縮・一括圧縮・状態照会・コールバック通知の4つの主にインターフェースを提供し、単一ファイルから一括処理まで幅広いシーンをカバーしています。認証方法は2つから選べます。サーバー側にはAPI Key、フロントエンドにはBearer Tokenが適しています。レート制限のポリシーは明確で、デフォルトは1分あたり60リクエスト、エンタープライズ版は300リクエストです。429ステータスコードを受け取ったら指数バックオフで再試行します。80MBのスキャンPDFは6.5秒で8.2MBまで圧縮でき、圧縮率は89.8%です。
3つのポイントを覚えておいてください。1つは、50MB以下は同期のに結果が返り、それ以上なら非同期でタスクIDを照会すること。2つは、レート制限429のときは指数バックオフで再試行し、無理に連投しないこと。3つは、大容量ファイルは分割アップロードインターフェースを使い、5MBずつ区切ってアップロードすることです。インターフェースとパラメータを正しく選べば、圧縮APIの呼び出しは決して難しくありません。HTTP呼び出しよりもローカルSDK統合をお望みの場合は、圧縮SDK統合ガイドをご参照ください。
関連記事
ファイルを圧縮ませんか？SmartSlimをお試しください
独自開発のRust製圧縮エンジンをベースに、PDF／画像／動画／Office／OFDなど10ジャンル40以上の形式に対応。ローカル圧縮でデータは社外に出しません。