📌 خروجی پروژه:

🔹 API تبدیل JPEG و PNG به WebP

🔹 تبدیل تصویر به AVIF با AV1

🔹 Resize خودکار تصویر

🔹 حفظ نسبت طول و عرض

🔹 جلوگیری از Upscale ناخواسته

🔹 تنظیم Quality از طریق API

🔹 محدودیت حجم Upload

🔹 محدودیت تعداد Pixel برای تصاویر بسیار بزرگ

🔹 احراز هویت API با API Key

🔹 اجرا پشت Nginx و HTTPS

نسخه فعلی هنگام نگارش: libvips 8.18.6

Binding مورد استفاده: pyvips

Backend AVIF: libheif + AV1 encoder

اجرای Image API روی سرور مجازی ایران

اگر تصاویر سایت یا اپلیکیشن شما عمدتاً برای کاربران داخل ایران پردازش می‌شوند، می‌توانید این سرویس را روی سرور مجازی ایران اجرا کنید و Application اصلی تصاویر را برای تبدیل به این API ارسال کند.

sudo apt update
sudo apt upgrade -y

sudo apt install 
  python3 
  python3-venv 
  python3-pip 
  nginx 
  libvips-tools 
  libvips-dev 
  libheif1 
  libheif-plugin-aomenc 
  libheif-plugin-aomdec 
  -y

vips --version

vips -l | grep -E "webpsave|heifsave"

⚠️ نکته: AVIF در libvips از HEIF Writer با Compression نوع AV1 ساخته می‌شود. اگر libheif روی سیستم بدون AV1 Encoder نصب شده باشد، تولید AVIF کار نخواهد کرد. روی Ubuntu 24.04 بسته libheif-plugin-aomenc برای Encoder مبتنی بر AOM در دسترس است.

sudo mkdir -p /opt/image-converter

sudo useradd 
  --system 
  --home /opt/image-converter 
  --shell /usr/sbin/nologin 
  imageapi

sudo chown -R imageapi:imageapi 
  /opt/image-converter

sudo -u imageapi \
  python3 -m venv \
  /opt/image-converter/venv

sudo -u imageapi 
  /opt/image-converter/venv/bin/pip 
  install --upgrade pip

sudo -u imageapi 
  /opt/image-converter/venv/bin/pip 
  install 
  fastapi 
  uvicorn 
  python-multipart 
  pyvips

sudo nano /opt/image-converter/app.py

import os
import secrets
import tempfile
from pathlib import Path
from typing import Literal

import pyvips
from fastapi import (
    FastAPI,
    File,
    Form,
    Header,
    HTTPException,
    UploadFile,
)
from fastapi.responses import Response


app = FastAPI(
    title="Iranica Image Converter"
)

API_KEY = os.getenv(
    "IMAGE_API_KEY",
    ""
)

MAX_UPLOAD_BYTES = 25 * 1024 * 1024
MAX_PIXELS = 60_000_000

ALLOWED_TYPES = {
    "image/jpeg",
    "image/png",
    "image/webp",
    "image/avif",
    "image/heic",
}


def check_api_key(value: str | None):
    if not API_KEY:
        return

    if not secrets.compare_digest(
        value or "",
        API_KEY
    ):
        raise HTTPException(
            status_code=401,
            detail="Invalid API key"
        )


def resize_down(
    image,
    width: int | None,
    height: int | None,
):
    scales = []

    if width:
        scales.append(
            width / image.width
        )

    if height:
        scales.append(
            height / image.height
        )

    if not scales:
        return image

    scale = min(scales)

    # از بزرگ کردن تصویر جلوگیری می‌کنیم.
    scale = min(scale, 1.0)

    if scale >= 1.0:
        return image

    return image.resize(
        scale,
        kernel="lanczos3"
    )


@app.get("/health")
def health():
    return {
        "status": "ok",
        "libvips": pyvips.version(0),
    }


@app.post("/convert")
async def convert_image(
    file: UploadFile = File(...),
    format: Literal["webp", "avif"] = Form("webp"),
    quality: int = Form(80),
    width: int | None = Form(None),
    height: int | None = Form(None),
    x_api_key: str | None = Header(None),
):
    check_api_key(x_api_key)

    if file.content_type not in ALLOWED_TYPES:
        raise HTTPException(
            status_code=415,
            detail="Unsupported image type"
        )

    if quality < 20 or quality > 100:
        raise HTTPException(
            status_code=400,
            detail="Quality must be 20-100"
        )

    if width is not None and (
        width < 1 or width > 8000
    ):
        raise HTTPException(
            status_code=400,
            detail="Invalid width"
        )

    if height is not None and (
        height < 1 or height > 8000
    ):
        raise HTTPException(
            status_code=400,
            detail="Invalid height"
        )

    suffix = Path(
        file.filename or "upload.bin"
    ).suffix[:12]

    temp_path = None
    total = 0

    try:
        with tempfile.NamedTemporaryFile(
            suffix=suffix,
            delete=False
        ) as temp:
            temp_path = temp.name

            while True:
                chunk = await file.read(
                    1024 * 1024
                )

                if not chunk:
                    break

                total += len(chunk)

                if total > MAX_UPLOAD_BYTES:
                    raise HTTPException(
                        status_code=413,
                        detail="Image too large"
                    )

                temp.write(chunk)

        try:
            image = pyvips.Image.new_from_file(
                temp_path,
                access="sequential",
                fail_on="error"
            )

        except pyvips.Error:
            raise HTTPException(
                status_code=422,
                detail="Invalid image"
            )

        pixels = (
            image.width
            * image.height
        )

        if pixels > MAX_PIXELS:
            raise HTTPException(
                status_code=413,
                detail="Too many pixels"
            )

        # EXIF Orientation را اعمال می‌کند.
        image = image.autorot()

        image = resize_down(
            image,
            width,
            height
        )

        if format == "webp":
            output = image.webpsave_buffer(
                Q=quality,
                effort=4,
                smart_subsample=True
            )

            media_type = "image/webp"
            extension = "webp"

        else:
            output = image.heifsave_buffer(
                Q=quality,
                compression="av1",
                encoder="aom",
                effort=4
            )

            media_type = "image/avif"
            extension = "avif"

        source_name = Path(
            file.filename or "image"
        ).stem

        response = Response(
            content=bytes(output),
            media_type=media_type
        )

        response.headers[
            "Content-Disposition"
        ] = (
            f'inline; filename="'
            f'{source_name}.{extension}"'
        )

        response.headers[
            "Cache-Control"
        ] = "no-store"

        return response

    finally:
        await file.close()

        if temp_path:
            try:
                os.unlink(temp_path)
            except FileNotFoundError:
                pass

openssl rand -hex 32

sudo nano \
/etc/systemd/system/image-converter.service

[Unit]
Description=Image WebP AVIF Converter API
After=network.target

[Service]
User=imageapi
Group=imageapi

WorkingDirectory=/opt/image-converter

Environment="IMAGE_API_KEY=YOUR_SECRET_API_KEY"
Environment="VIPS_CONCURRENCY=2"

ExecStart=/opt/image-converter/venv/bin/uvicorn 
    app:app 
    --host 127.0.0.1 
    --port 8100 
    --workers 2

Restart=on-failure
RestartSec=3

NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now image-converter
sudo systemctl status image-converter

server {
    listen 80;
    server_name image-api.example.com;

    client_max_body_size 25m;

    location / {
        proxy_pass http://127.0.0.1:8100;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 120s;
    }
}

curl -X POST \
  https://image-api.example.com/convert \
  -H "X-API-Key: YOUR_SECRET_API_KEY" \
  -F "file=@photo.jpg" \
  -F "format=webp" \
  -F "quality=82" \
  -F "width=1200" \
  --output photo.webp

curl -X POST \
  https://image-api.example.com/convert \
  -H "X-API-Key: YOUR_SECRET_API_KEY" \
  -F "file=@photo.jpg" \
  -F "format=avif" \
  -F "quality=70" \
  -F "width=1200" \
  --output photo.avif

✅ API را بدون API Key عمومی نکنید.

✅ حجم Upload را محدود کنید.

✅ تعداد Pixel تصویر را محدود کنید.

✅ سیستم و libvips را به‌روز نگه دارید.

✅ فایل ورودی را با نام اصلی در مسیر عمومی ذخیره نکنید.

✅ Uvicorn را مستقیماً روی اینترنت باز نکنید.

✅ HTTPS را فعال کنید.

✅ Rate Limit روی Nginx یا API Gateway اضافه کنید.

POST /convert?url=https://example.com/photo.jpg

vips -l | grep heifsave

dpkg -l | grep libheif-plugin-aomenc

جمع‌بندی

با Python، FastAPI و libvips می‌توان بدون سرویس خارجی یک API شخصی برای تبدیل و Resize تصویر ساخت. WebP برای تبدیل سریع و AVIF برای سناریوهایی که Compression بیشتر ارزش مصرف CPU را دارد، قابل استفاده هستند.

برای محیط Production مهم‌ترین بخش‌ها فقط کد Conversion نیستند؛ محدودیت حجم و Pixel، Rate Limit، API Key، HTTPS و به‌روزرسانی libvips نیز باید در طراحی لحاظ شوند.

در مرحله بعد می‌توان همین API را به Object Storage، CDN شخصی، WordPress، Laravel یا اپ موبایل متصل کرد تا بهینه‌سازی تصاویر کاملاً خودکار شود.

منابع رسمی

مستندات pyvips

نسخه‌های libvips

آپلود فایل در FastAPI