Linux/Pythonで保存済み画像を生成AIに説明させる設計

カメラ画像はNASへ保存できているのに、あとから内容を確認するには画像を1枚ずつ開かなければならない。画像説明を生成AIに任せたくても、「撮影部分まで作り直す必要があるのか」「同じ画像を何度もAPIへ送らないか」が気になるところです。

この記事では、Linux/Python環境から撮影済みの静止画を1枚だけ読み、画像対応APIへ渡して、説明文と処理状態を保存する設計例を紹介します。撮影やNAS構築には手を加えません。まず1枚でデータの対応関係と失敗時の扱いを固めるのがポイントです。Raspberry Piはこの構成の応用先として扱います。

適用範囲：掲載例はx86_64 Linuxを前提に整理した設計例です。Raspberry Pi実機、NAS、カメラとの連携は検証していません。したがって、Raspberry Piでの動作時間、導入時間、互換性、API出力の再現性を示す記事ではありません。実機へ導入する場合は、OS、CPUアーキテクチャ、Python・SDKの対応状況を公式資料で確認し、架空画像1枚から試してください。

今回作るもの
Gemini APIを使う最小準備
保存済み画像を1枚だけ処理する
画像と説明を取り違えないための状態管理
1. 定期処理へ広げる場合
公開前に確認する4種類の画像
撮影処理は必要になってから追加する
まとめ

今回作るもの

前提は、Linux/Python環境から画像ファイルを通常のファイルとして読めることです。Raspberry Piへ応用する場合も同じ構成を使います。NASを使う場合は、すでにマウント済みのディレクトリとして扱います。

IPカメラやCamera Module
        ↓ 撮影
NASまたは保存ディレクトリ
        ↓ 保存済み画像を1枚読む
Linux上のPython処理（Raspberry Piを含む）
        ↓ HTTPS
画像対応API
        ↓
説明文 + 画像ID + 処理状態を保存

IPカメラやCamera Module

↓ 撮影

NASまたは保存ディレクトリ

↓ 保存済み画像を1枚読む

Linux上のPython処理（Raspberry Piを含む）

↓ HTTPS

画像対応API

↓

説明文 + 画像ID + 処理状態を保存

撮影、保存、AI処理を分けておけば、API側の問題による撮影処理への影響を分けやすくなります。また、新しいカメラを購入しなくても、Raspberry Piから読めるJPEGまたはPNGで試せます。

Gemini APIを使う最小準備

2026年9月11日にGoogle公式資料を確認した時点では、Python SDKは google-genai、画像入力に利用できるモデルは gemini-3.8-flash です。ここでは再現条件をそろえるため、同日にPyPIで公開を確認した google-genai==2.23.0 と Pillow==12.3.0 を指定します。どちらもPython 3.10以上が必要です。APIやモデルは変更されるため、公開時と実装時に公式資料を再確認してください。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install google-genai==2.23.0 Pillow==12.3.0
read -rsp 'Gemini API key: ' GEMINI_API_KEY
echo
export GEMINI_API_KEY

python3 -m venv .venv

source .venv/bin/activate

python -m pip install google-genai==2.23.0 Pillow==12.3.0

read -rsp 'Gemini API key: ' GEMINI_API_KEY

echo

export GEMINI_API_KEY

APIキーは非表示入力で現在のシェルの環境変数へ設定し、Pythonファイルやコマンド履歴へ直接書きません。エラーログや画面共有にも残さない運用が必要です。画像を外部APIへ送ってよいか、利用条件やデータの扱いも事前に確認してください。人物や顧客情報が写る実画像ではなく、最初は記事専用の架空画像を使います。

保存済み画像を1枚だけ処理する

次の例は、画像の向きをEXIF情報に合わせ、長辺を最大1,600ピクセルへ縮小してJPEGとして送ります。元画像は変更しません。元ファイルのSHA-256ハッシュを画像IDにし、同じ内容の状態ファイルがあれば自動では再送しない構成です。

import base64
import hashlib
import json
import time
from datetime import datetime, timezone
from io import BytesIO
from pathlib import Path

from google import genai
from PIL import Image, ImageOps

MODEL = "gemini-3.8-flash"
INPUT_PATH = Path("sample-images/frame-001.jpg")
RESULT_DIR = Path("image-descriptions")
MAX_LONG_EDGE = 1600


def now_iso():
    return datetime.now(timezone.utc).isoformat()


def write_state(path, data):
    temporary = path.with_suffix(".tmp")
    temporary.write_text(
        json.dumps(data, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )
    temporary.replace(path)


def prepare_image(path):
    with Image.open(path) as image:
        image = ImageOps.exif_transpose(image)
        image.thumbnail((MAX_LONG_EDGE, MAX_LONG_EDGE))

        if image.mode != "RGB":
            if "A" in image.getbands():
                background = Image.new("RGB", image.size, "white")
                background.paste(image, mask=image.getchannel("A"))
                image = background
            else:
                image = image.convert("RGB")

        output = BytesIO()
        image.save(output, format="JPEG", quality=85)
        return output.getvalue(), image.size


original_bytes = INPUT_PATH.read_bytes()
image_id = hashlib.sha256(original_bytes).hexdigest()
RESULT_DIR.mkdir(parents=True, exist_ok=True)
state_path = RESULT_DIR / f"{image_id}.json"

if state_path.exists():
    raise SystemExit(
        f"処理記録があるため自動送信しません: {state_path}"
    )

image_bytes, image_size = prepare_image(INPUT_PATH)
state = {
    "status": "sending",
    "image_id": image_id,
    "source_name": INPUT_PATH.as_posix(),
    "prepared_size": list(image_size),
    "prepared_mime_type": "image/jpeg",
    "model": MODEL,
    "request_attempts": 1,
    "updated_at": now_iso(),
}
write_state(state_path, state)

try:
    started = time.monotonic()
    client = genai.Client()
    interaction = client.interactions.create(
        model=MODEL,
        store=False,
        input=[
            {
                "type": "text",
                "text": (
                    "画像から観察できる内容だけを、日本語で簡潔に説明してください。"
                    "人物の特定、異常・故障・危険の断定、見えない情報の推測はしないでください。"
                ),
            },
            {
                "type": "image",
                "data": base64.b64encode(image_bytes).decode("utf-8"),
                "mime_type": "image/jpeg",
            },
        ],
    )
    description = (interaction.output_text or "").strip()
    if not description:
        raise RuntimeError("empty_response")

    state.update({
        "status": "succeeded",
        "description": description,
        "elapsed_seconds": round(time.monotonic() - started, 3),
        "usage": {
            "input_tokens": interaction.usage.total_input_tokens,
            "output_tokens": interaction.usage.total_output_tokens,
            "thought_tokens": interaction.usage.total_thought_tokens,
            "total_tokens": interaction.usage.total_tokens,
        },
        "updated_at": now_iso(),
    })
    write_state(state_path, state)
except Exception as error:
    state.update({
        "status": "needs_review",
        "error_type": type(error).__name__,
        "elapsed_seconds": round(time.monotonic() - started, 3),
        "updated_at": now_iso(),
    })
    write_state(state_path, state)
    raise

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

import base64

import hashlib

import json

import time

from datetime import datetime, timezone

from io import BytesIO

from pathlib import Path

from google import genai

from PIL import Image, ImageOps

MODEL = "gemini-3.8-flash"

INPUT_PATH = Path("sample-images/frame-001.jpg")

RESULT_DIR = Path("image-descriptions")

MAX_LONG_EDGE = 1600

def now_iso():

return datetime.now(timezone.utc).isoformat()

def write_state(path, data):

temporary = path.with_suffix(".tmp")

temporary.write_text(

json.dumps(data, ensure_ascii=False, indent=2),

encoding="utf-8",

)

temporary.replace(path)

def prepare_image(path):

with Image.open(path) as image:

image = ImageOps.exif_transpose(image)

image.thumbnail((MAX_LONG_EDGE, MAX_LONG_EDGE))

if image.mode != "RGB":

if "A" in image.getbands():

background = Image.new("RGB", image.size, "white")

background.paste(image, mask=image.getchannel("A"))

image = background

else:

image = image.convert("RGB")

output = BytesIO()

image.save(output, format="JPEG", quality=85)

return output.getvalue(), image.size

original_bytes = INPUT_PATH.read_bytes()

image_id = hashlib.sha256(original_bytes).hexdigest()

RESULT_DIR.mkdir(parents=True, exist_ok=True)

state_path = RESULT_DIR / f"{image_id}.json"

if state_path.exists():

raise SystemExit(

f"処理記録があるため自動送信しません: {state_path}"

)

image_bytes, image_size = prepare_image(INPUT_PATH)

state = {

"status": "sending",

"image_id": image_id,

"source_name": INPUT_PATH.as_posix(),

"prepared_size": list(image_size),

"prepared_mime_type": "image/jpeg",

"model": MODEL,

"request_attempts": 1,

"updated_at": now_iso(),

}

write_state(state_path, state)

try:

started = time.monotonic()

client = genai.Client()

interaction = client.interactions.create(

model=MODEL,

store=False,

input=[

{

"type": "text",

"text": (

"画像から観察できる内容だけを、日本語で簡潔に説明してください。"

"人物の特定、異常・故障・危険の断定、見えない情報の推測はしないでください。"

{

"type": "image",

"data": base64.b64encode(image_bytes).decode("utf-8"),

"mime_type": "image/jpeg",

)

description = (interaction.output_text or "").strip()

if not description:

raise RuntimeError("empty_response")

state.update({

"status": "succeeded",

"description": description,

"elapsed_seconds": round(time.monotonic() - started, 3),

"usage": {

"input_tokens": interaction.usage.total_input_tokens,

"output_tokens": interaction.usage.total_output_tokens,

"thought_tokens": interaction.usage.total_thought_tokens,

"total_tokens": interaction.usage.total_tokens,

"updated_at": now_iso(),

})

write_state(state_path, state)

except Exception as error:

state.update({

"status": "needs_review",

"error_type": type(error).__name__,

"elapsed_seconds": round(time.monotonic() - started, 3),

"updated_at": now_iso(),

})

write_state(state_path, state)

raise

入力パスは例示用です。実在するサーバー名、IPアドレス、共有名はコードやログに残さないでください。この例では、単発処理の会話状態をInteractions API側へ保存しないよう store=False を指定し、画像はインラインで送ります。Google公式資料では、インラインデータは小さい画像向けで、大きい画像や繰り返し使う画像にはFiles APIが案内されています。store=False とは別に適用される利用条件やデータの扱いも、実装時に確認してください。

画像と説明を取り違えないための状態管理

ファイル名だけでは、同名の別画像と区別できません。そこで、元画像の内容から作ったハッシュをIDとして使います。状態ファイルには、少なくとも次の情報を残します。

項目	用途
`image_id`	元画像のハッシュ
`source_name`	入力ファイルの相対的な名前
`status`	送信前、成功、要確認の区別
`model`	呼び出したモデル名
`updated_at`	処理日時
`description`	成功した場合だけ保存する応答本文
`elapsed_seconds` / `usage`	API処理時間と応答のトークン使用量

通信が途中で切れた場合、API側で処理されたかをクライアント側だけでは判断できないことがあります。上のコードは例外時を needs_review とし、状態ファイルが残っている画像を自動再送しません。担当者がAPIの利用記録と状態ファイルを確認してから、手動で再処理を判断します。

定期処理へ広げる場合

1回の対象件数、再試行上限、待機時間、呼び出し回数を設定します。NAS切断、破損画像、認証失敗、レート制限、空応答も別々に記録すると、原因を追いやすくなります。元画像、説明文、処理記録の保存期間は、それぞれの目的に合わせて決めます。

公開前に確認する4種類の画像

コードが動くだけでは、説明が用途に合うかは分かりません。公開前に記事専用の画像を用意し、次の観点で人が元画像と応答を照合します。

実行結果を公開する場合は、通常・暗い・ぶれ・対象なしの各入力画像を権利と機密性を確認したうえで掲載し、画像ごとのSHA-256、実行コマンド、応答JSON、モデル、SDK、実行日時を対応づけます。入力画像を公開できない場合は、処理時間やトークン数、応答抜粋を再現可能な実測結果として掲載しません。

通常：主要な物や配置が、画像から確認できる範囲で説明されるか
暗い：見えない内容を推測して断定していないか
ぶれ：不鮮明な対象を具体的な物として決めつけていないか
対象なし：何もない状態に、存在しない対象を付け加えていないか

画像説明は観察を補助する候補であり、事実の保証ではありません。人物特定、防犯判断、異常検知、設備の故障診断、自動通報へそのまま使わないでください。処理時間や使用量を掲載する場合は、Raspberry Piの機種、OS、ネットワーク、画像サイズ、SDKとモデル、測定回数をそろえ、実測値だけを記録します。

画像を保存する側の構成は、IPカメラとRaspberry PiのNASを組み合わせた過去の制作記録を参照できます。撮影・保存と画像説明の処理を分ける例として読み、旧機器やFTPの手順をそのまま新規導入へ流用しないでください。

撮影処理は必要になってから追加する

今回の処理にカメラは必須ではありません。Raspberry Pi公式資料では、Raspberry Pi OS Bookworm以降のカメラ用コマンドは rpicam-* という名前で、静止画には rpicam-still、Pythonからの撮影にはPicamera2が案内されています。必要になった段階で、撮影先を入力ディレクトリへ合わせれば十分です。

Raspberry Pi AI Cameraは、Sony IMX500センサー上でニューラルネットワークの推論を行う別の構成です。本記事のクラウドAPIによる画像説明とは役割が異なるため、同じものとして扱いません。

まとめ

Linux/Python環境から保存済み画像の説明処理を設計するときは、撮影や保存を作り直さず、画像1枚から始められます。元画像のハッシュ、説明文、モデル名、処理状態を対応づけ、通信結果が曖昧なときは自動再送しないようにします。Raspberry Piへ応用する場合は、実機条件を記録し、人が元画像と説明を照合してから対象件数や定期実行を増やしてください。

公式資料確認日：2026年9月11日。参照：Google「Getting started」、Google「Image understanding」、Google「Interactions API」、Raspberry Pi「Camera software」、Raspberry Pi「AI Camera」。API、SDK、モデル、上限、料金、データ条件は変更されるため、実装時にも公式資料を確認してください。