Python と Flask によるシンプルな画像処理 API の作成
小規模な画像 API を作ると、アップロード、デコーダー、HTTP レスポンスの連携を学べます。ここでは Flask と Pillow を使い、指定サイズに画像を引き伸ばすものと、PNG または JPEG に変換するものの 2 つのエンドポイントを構築します。どちらも同じ検証とエンコードの処理経路を使います。
これはループバックで動作する開発用サービスであり、認証付きの公開アップロードサービスではありません。ファイルサイズ、ピクセル数、同時実行数の制限はリソース使用量を抑えますが、ネイティブデコーダーをサンドボックス化するものではありません。
画像処理 API の概要
リクエストには、マルチパート形式のファイル 1 個と操作パラメーターを含めます。サーバーはデコードした形式と寸法を検証し、操作を実行して画像のバイト列を返します。ファイル名やブラウザーが指定した MIME タイプは、アップロードの安全性を示す根拠にはなりません。
開発環境のセットアップ
Linux 上で Python 3.12 以降、Bash、cURL を使います。ファイルを作成する前に python3 --version を確認し、curl --help all に --fail-with-body が含まれることを確認してください。新しいディレクトリで requirements.txt を作成します。
Flask==3.1.3
Pillow==12.3.0
Flask-Limiter==4.1.1
gunicorn==26.2.0
続いて、仮想環境にインストールします。
python3 -m venv .venv &&
source .venv/bin/activate &&
python -m pip install -r requirements.txt
環境の作成やインストールに失敗した場合は、エラーを解決してから、同じディレクトリでセットアップのブロックを再実行してください。requirements.txt とソースファイルは残します。コマンドは失敗した手順で停止します。仮想環境により、この例のパッケージを、上位ディレクトリにある Python プロジェクトから分離できます。
基本的な Flask アプリケーションの作成
次のアプリケーション全体を app.py に保存してください。起動用のブロックは、すべてのルートとハンドラーの後に 1 つだけあります。
import io
import re
import threading
import warnings
from flask import Flask, request, send_file
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address
from PIL import Image, ImageOps, UnidentifiedImageError
from werkzeug.exceptions import BadRequest, HTTPException
MAX_BYTES = 8 * 1024 * 1024
MAX_PIXELS = 12_000_000
MAX_SIDE = 2048
Image.MAX_IMAGE_PIXELS = MAX_PIXELS
warnings.simplefilter("error", Image.DecompressionBombWarning)
app = Flask(__name__)
# Leave room for Werkzeug's 64 KiB multipart parser chunks, including framing.
app.config.update(MAX_CONTENT_LENGTH=MAX_BYTES + 64 * 1024,
MAX_FORM_MEMORY_SIZE=128 * 1024, MAX_FORM_PARTS=8)
limiter = Limiter(get_remote_address, app=app,
default_limits=["60 per minute"], storage_uri="memory://")
slots = threading.BoundedSemaphore(2)
def dimension(name, default):
values = request.form.getlist(name)
text = values[0] if len(values) == 1 else default
if len(values) > 1 or re.fullmatch(r"[0-9]{1,4}", text) is None:
raise BadRequest()
value = int(text)
if not 1 <= value <= MAX_SIDE:
raise BadRequest()
return value
def load_image():
files = request.files.getlist("file")
if len(files) != 1 or len(request.files) != 1:
raise BadRequest()
data = files[0].read(MAX_BYTES + 1)
if not data or len(data) > MAX_BYTES:
raise BadRequest()
with Image.open(io.BytesIO(data), formats=("JPEG", "PNG")) as source:
# Pillow exposes some 16-bit PNGs as RGB/RGBA, so mode alone cannot enforce this limit.
if source.format == "PNG" and (data[12:16] != b"IHDR" or data[24] > 8):
raise BadRequest()
if source.width * source.height > MAX_PIXELS or getattr(source, "n_frames", 1) != 1:
raise BadRequest()
source.load()
oriented = ImageOps.exif_transpose(source)
try:
return oriented.convert("RGBA")
finally:
oriented.close()
def encode_image(image, target):
image.info.clear()
output = io.BytesIO()
if target == "JPEG":
background = Image.new("RGB", image.size, "white")
try:
background.paste(image, mask=image.getchannel("A"))
background.save(output, format="JPEG", quality=85)
finally:
background.close()
else:
image.save(output, format="PNG")
output.seek(0)
response = send_file(output, mimetype=Image.MIME[target],
download_name="result." + ("jpg" if target == "JPEG" else "png"))
response.headers["Cache-Control"] = "no-store"
response.headers["X-Content-Type-Options"] = "nosniff"
return response
def process_image(resize):
if not slots.acquire(blocking=False):
return {"error": "Image processor is busy."}, 503
try:
allowed = {"width", "height"} if resize else {"format"}
if any(name not in allowed for name in request.form):
raise BadRequest()
formats = request.form.getlist("format")
target = formats[0].upper() if formats else "PNG"
if len(formats) > 1 or target not in ("PNG", "JPEG"):
raise BadRequest()
width = dimension("width", "100") if resize else None
height = dimension("height", "100") if resize else None
with load_image() as image:
if resize:
with image.resize((width, height), Image.Resampling.LANCZOS) as result:
return encode_image(result, "PNG")
return encode_image(image, target)
except (BadRequest, UnidentifiedImageError, OSError, ValueError,
Image.DecompressionBombError, Image.DecompressionBombWarning):
return {"error": "Provide one valid single-frame JPEG or PNG and supported parameters."}, 400
finally:
slots.release()
@app.post("/resize")
def resize_image():
return process_image(resize=True)
@app.post("/convert")
def convert_image():
return process_image(resize=False)
@app.errorhandler(HTTPException)
def http_error(error):
messages = {413: "Upload is too large.", 429: "Too many requests."}
return {"error": messages.get(error.code, "Request could not be processed.")}, error.code
@app.errorhandler(Exception)
def unexpected_error(error):
# Avoid logging file content, headers or untrusted decoder messages.
app.logger.error("Unexpected image processing failure: %s", type(error).__name__)
return {"error": "Image processing failed."}, 500
if __name__ == "__main__":
app.run(host="127.0.0.1", port=5000, debug=False)
画像処理への Pillow の組み込み
load_image() は JPEG と PNG のデコーダーだけを開きます。この例では、チャンネルあたり最大 8 ビットの PNG を受け付け、16 ビット PNG は数値範囲を暗黙に変更せずに拒否します。アニメーション PNG も拒否し、画像を読み込む前にデコード後のピクセル数を検証します。EXIF の向きを適用し、共通の処理経路で使う RGBA ピクセルを生成します。出力では、埋め込まれた GPS データを含む元のメタデータを意図的に除去します。ICC カラープロファイルは適用しないため、カラーマネジメント対象の入力は事前に sRGB に変換してください。
Pillow の画像モードのドキュメントでは、8 ビット RGBA 表現とその制約を説明しています。
8 MiB のファイル制限は、マルチパートリクエストの制限とは別です。圧縮後のファイルサイズや寸法だけでは、すべてのデコーダーの CPU とメモリの使用量を制限できません。Pillow を最新に保ち、公開サービスの処理ワーカーは OS のリソース制限を使って隔離してください。
画像リサイズ用エンドポイントの実装
python app.py でアプリケーションを起動します。起動したまま、cURL 用に別のターミナルを同じディレクトリで開いてください。そこに photo.jpg という名前のローカル JPEG を配置し、リサイズします。
curl --fail-with-body -F "file=@photo.jpg" -F "width=300" -F "height=200" \
http://127.0.0.1:5000/resize --output resized.png
成功すると、このコマンドは 300 × 200 の PNG を返します。この操作は画像を引き伸ばすため、アスペクト比を維持しません。出力の各辺は 1 ピクセル以上 2048 ピクセル以下にする必要があります。アスペクト比を維持したサムネイルには、要求された寸法を暗黙に変更するのではなく、フィットまたは切り抜きの方針を明示的に選んでください。
resized.png を開いて内容を確認してください。cURL は再実行に成功すると、指定した出力ファイルを置き換えます。--fail-with-body を使うと、HTTP エラー時に同じファイルへ JSON が書き込まれる場合があるため、cURL の終了ステータスも確認してください。
画像形式変換用エンドポイントの追加
/convert は、大文字と小文字を区別せずに
PNG または JPEG を受け付けます。PNG は透明度を維持します。JPEG は透明度を表現できないため、この例では透明なピクセルを白い背景に合成します。同じディレクトリに transparent.png という名前の
8 ビット PNG を配置し、変換してください。
curl --fail-with-body -F "file=@transparent.png" -F "format=JPEG" \
http://127.0.0.1:5000/convert --output converted.jpg
converted.jpg を開いてください。透明な領域は白くなり、半透明のピクセルは白と混ざるはずです。どちらのエンドポイントも画像を直接返し、アプリケーションはアップロードや結果をサーバーに保存しません。終了したら Ctrl+C でサーバーを停止してください。
サンプルリクエストによる API のテスト
次のテストを test_app.py に保存し、python -m unittest -v を実行してください。Flask のテストクライアントは、サーバーを起動せずに実際のリクエストパーサーと Pillow エンコーダーを動作させます。
import io
import random
import unittest
from PIL import Image
from app import app, limiter
class ImageApiTest(unittest.TestCase):
def setUp(self):
app.config.update(TESTING=True)
limiter.enabled = False
self.client = app.test_client()
def upload(self, path, input_format="PNG", **fields):
image = io.BytesIO()
mode = "RGB" if input_format == "JPEG" else "RGBA"
with Image.new(mode, (80, 40), (200, 40, 80) if mode == "RGB" else (200, 40, 80, 128)) as source:
source.paste((20, 60, 220) if mode == "RGB" else (20, 60, 220, 255), (52, 0, 80, 40))
if mode == "RGBA":
source.paste((0, 150, 250, 0), (0, 0, 24, 40))
source.save(image, input_format)
image.seek(0)
return self.client.post(path, data={"file": (image, "photo"), **fields})
def assert_pixel(self, image, position, expected, tolerance=5):
for actual, wanted in zip(image.getpixel(position), expected):
self.assertLessEqual(abs(actual - wanted), tolerance)
def test_resize(self):
response = self.upload("/resize", width="12", height="8")
self.assertEqual(response.status_code, 200)
with Image.open(io.BytesIO(response.data)) as image:
self.assertEqual((image.format, image.size), ("PNG", (12, 8)))
self.assertEqual(image.getpixel((0, 0))[3], 0)
self.assert_pixel(image, (11, 7), (20, 60, 220, 255))
def test_alpha_to_jpeg(self):
response = self.upload("/convert", format="JPEG")
self.assertEqual(response.status_code, 200)
with Image.open(io.BytesIO(response.data)) as image:
self.assertEqual(image.format, "JPEG")
self.assert_pixel(image, (8, 20), (255, 255, 255))
self.assert_pixel(image, (38, 20), (227, 147, 167))
self.assert_pixel(image, (70, 20), (20, 60, 220))
def test_jpeg_input(self):
response = self.upload("/resize", input_format="JPEG", width="10", height="5")
self.assertEqual(response.status_code, 200)
with Image.open(io.BytesIO(response.data)) as image:
self.assertEqual((image.format, image.size), ("PNG", (10, 5)))
self.assert_pixel(image, (0, 0), (200, 40, 80, 255))
self.assert_pixel(image, (9, 4), (20, 60, 220, 255))
def test_rejects_16_bit_png(self):
data = io.BytesIO()
with Image.new("I;16", (40, 20), 32768) as image:
image.save(data, "PNG")
data.seek(0)
response = self.client.post("/convert", data={"file": (data, "gray.png")})
self.assertEqual(response.status_code, 400)
def test_multipart_file_larger_than_a_parser_chunk(self):
data = io.BytesIO()
pixels = random.Random(0).randbytes(512 * 512 * 3)
with Image.frombytes("RGB", (512, 512), pixels) as image:
image.save(data, "JPEG", quality=90)
self.assertGreater(data.tell(), 64 * 1024)
data.seek(0)
response = self.client.post("/resize", data={"file": (data, "photo.jpg")})
self.assertEqual(response.status_code, 200)
with Image.open(io.BytesIO(response.data)) as image:
self.assertEqual(image.size, (100, 100))
def test_invalid_dimensions(self):
for width in ("0", "-1", "2049", "NaN", "12px"):
with self.subTest(width=width):
self.assertEqual(self.upload("/resize", width=width).status_code, 400)
def test_invalid_upload(self):
response = self.client.post("/resize", data={"file": (io.BytesIO(b"invalid"), "x.png")})
self.assertEqual(response.status_code, 400)
if __name__ == "__main__":
unittest.main()
エラー処理と入力検証
想定される不正な入力には汎用の 400 レスポンスを返し、サイズ超過の HTTP リクエストには 413 を返します。各エンドポイントは、クライアント IP ごとに毎分 60 リクエストを許可します。レート制限に達すると 429 を返し、処理スロットが両方とも使用中にアプリケーションに到達したリクエストには 503 を返します。ただし、アプリケーションに到達する前に HTTP サーバーが接続をキューに入れることはできます。予期しない障害には機密情報を除いた 500 レスポンスを返し、デコーダーの例外やスタックトレースは決して返しません。HTTP リクエストの制限内でも、8 MiB を超えるファイルには 400 を返します。Flask のリソース使用量制限により、リクエスト、フォームフィールド、パート数に対して、それより前に 413 が返される場合があります。
Gunicorn によるローカル API の実行
Linux では、Gunicorn ワーカーを 1 つにすると、このデモのインメモリの制限を単一プロセス内に維持できます。
gunicorn --bind 127.0.0.1:5000 --workers 1 --threads 2 --timeout 30 \
--no-control-socket app:app
このリスナーはループバックに限定してください。リモートからのアップロードを受け付ける前に、認証付きの HTTPS エントリーポイントとワーカーの隔離を別途設定してください。オプションの管理ソケットは無効にしているため、このデモが他のローカルインスタンスと Gunicorn のデフォルトのソケットパスを共有することはありません。Ctrl+C でサーバーを停止できます。ワーカーの終了には、デフォルトの猶予期間である 30 秒までかかる場合があります。
ワーカーやインスタンスを追加する前に、Flask-Limiter のストレージに関するドキュメントに従って、共有のレート制限ストアを設定してください。メモリ上のカウンターは再起動時にリセットされ、プロセス間では共有されません。サーバーのタイムアウトは、Pillow の操作単位のキャンセル機構ではありません。
まとめと次のステップ
必要な形式や寸法に合わせてテストを拡充し、代表的なファイルでリソース使用量を測定してください。マネージドワークフローを利用するなら、デコーダー群を自前で運用する代わりに、Transloadit の画像処理サービスを検討してください。
