Gemini on KnightLi的博客

product-cutout-normalize：商品圖去背與標準化的 Agent Skill

Thu, 09 Apr 2026 21:43:50 +0800

product-cutout-normalize 是一個給商品圖使用的 Agent Skill。

它會把原圖處理成統一規格的透明底方圖。預設規則是：

1024x1024 畫布
透明背景
盡量完整保留主體
直向主體自動轉成橫向
主體置中
主體可視寬度統一到 820px

適合電商素材、商品庫和詳情頁圖片預處理。

這個 skill 解決什麼問題

很多商品圖做完基礎去背後，還是會有這些問題：

白邊或淺灰背景殘留
主體橫豎方向不一致
畫布大小不一致
主體大小忽大忽小
透明區域裡有小噪點

這個 skill 會按照固定流程處理：

用 Gemini 去背
清理邊緣淺色背景
去掉小碎片噪點
直圖轉橫圖
按目標寬度縮放
放到統一尺寸的透明畫布中央

這樣輸出的圖片會更整齊，也更適合批次使用。

適用場景

適合下面這些需求：

批次處理商品照片
統一輸出透明底 PNG
統一主視覺尺寸
需要穩定、可重複的處理流程

如果你只處理少量圖片，或每張圖都要單獨調整版面，那它未必適合。

快速開始

最直接的執行方式：

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite`

執行前需要：

GEMINI_API_KEY
google-genai
Pillow

安裝依賴：

`1`	`.\.venv\Scripts\python.exe -m pip install google-genai pillow`

設定環境變數：

`1`	`$env:GEMINI_API_KEY="your_api_key"`

輸出規則

預設輸出：

透明背景 PNG
1024x1024 畫布
主體寬度 820px
主體置中
小噪點會被清理

所以它不只是去背腳本，更像是一個商品圖整理腳本。

主要參數說明

常用參數：

--model 預設 gemini-2.5-flash-image
--canvas-size 輸出方形畫布尺寸，預設 1024
--target-width 主體可視寬度，預設 820
--min-component-pixels 小於這個像素數的透明碎片會被移除，預設 500
--overwrite 輸出檔案已存在時直接覆蓋

例如：

`1`	`& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" ".\input" ".\output" --canvas-size 1280 --target-width 960 --overwrite`

處理流程

處理流程很簡單：

用 Gemini 去背
清理邊緣淺色背景
去掉小碎片噪點
直圖轉橫圖
按目標寬度縮放
放到統一尺寸的透明畫布中央

和一般去背腳本的差別

和一般去背腳本相比，它還會額外處理這些問題：

主體方向統一
主體尺寸統一
畫布尺寸統一
小碎片噪點清理
結果更適合直接放進素材庫

SKILL.md 原始碼

下面保留 SKILL.md 的完整原始碼，內容不做改動：

---
name: product-cutout-normalize
description: Run a reusable Gemini product-image pipeline that removes backgrounds, preserves the full subject, rotates tall products to a horizontal orientation, centers them on a 1024x1024 transparent canvas, and normalizes the visible subject width to 820px. Use when the user wants a repeatable cutout-and-normalize workflow for product photos or asks to batch-process product images into standardized square PNG assets.
---

# Product Cutout Normalize

Use this skill when product photos need the same deterministic finishing pipeline:

- Gemini cutout from the original photo
- border cleanup to transparent
- preserve the full subject
- rotate to horizontal when the subject is taller than it is wide
- center on a `1024x1024` transparent canvas
- normalize the visible subject width to `820px`

## Quick Start

Run the bundled script:

```powershell
& ".\.venv\Scripts\python.exe" ".codex\skills\product-cutout-normalize\scripts\run_pipeline.py" "input_dir" "output_dir" --overwrite
```

Required environment:

- `GEMINI_API_KEY`
- `google-genai`
- `Pillow`

## Workflow

1. Confirm the request matches this standard pipeline. If the user asks for a different canvas size, subject width, or layout rule, pass explicit flags instead of changing the script.
2. Run the bundled script on the input directory.
3. If a result looks misaligned, inspect the alpha bounding box and small detached artifacts first; this pipeline already removes tiny alpha components by default.
4. Report the exact input and output directories used, plus any non-default flags.

## Script

Primary entry point:

- `scripts/run_pipeline.py`

Key flags:

- `--model`: Gemini image model, default `gemini-2.5-flash-image`
- `--canvas-size`: output square size, default `1024`
- `--target-width`: visible subject width after normalization, default `820`
- `--min-component-pixels`: remove detached alpha specks smaller than this, default `500`
- `--overwrite`: replace existing outputs in the destination directory

## Repo Integration

If the current project already has [`scripts/nano_banana_cutout.py`](/c:/Work/my_shop/scripts/nano_banana_cutout.py), prefer that repo script when the user wants the same pipeline inside this repository. Use the bundled skill script when the task is cross-project reuse or when you want the workflow to stay self-contained inside the skill.

scripts/run_pipeline.py 原始碼

下面保留 scripts/run_pipeline.py 的完整原始碼，內容不做改動：

from __future__ import annotations

import argparse
import os
from collections import deque
from pathlib import Path

from PIL import Image

try:
    from google import genai
except ImportError as exc:  # pragma: no cover
    raise SystemExit(
        "Missing dependency: google-genai. Install it with "
        r"'.\.venv\Scripts\python.exe -m pip install google-genai'."
    ) from exc


PROMPT = (
    "Remove the entire background from this product photo and return only the product "
    "on a fully transparent background as a PNG. Keep the full product intact, preserve "
    "thin cable details, clean the inner loops and holes, and do not add any new objects "
    "or shadows."
)
DEFAULT_CANVAS_SIZE = 1024
DEFAULT_TARGET_WIDTH = 820
DEFAULT_MIN_COMPONENT_PIXELS = 500
SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp"}


def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35


def to_pil_image(image_obj) -> Image.Image:
    if isinstance(image_obj, Image.Image):
        return image_obj
    pil_image = getattr(image_obj, "_pil_image", None)
    if isinstance(pil_image, Image.Image):
        return pil_image
    as_pil = getattr(image_obj, "pil_image", None)
    if isinstance(as_pil, Image.Image):
        return as_pil
    raise TypeError(f"Unsupported image object type: {type(image_obj)!r}")


def make_transparent_from_borders(image: Image.Image) -> Image.Image:
    rgba = image.convert("RGBA")
    width, height = rgba.size
    pixels = rgba.load()

    visited: set[tuple[int, int]] = set()
    queue: deque[tuple[int, int]] = deque()

    def push_if_bg(x: int, y: int) -> None:
        if (x, y) in visited:
            return
        r, g, b, _ = pixels[x, y]
        if is_light_background_pixel(r, g, b):
            visited.add((x, y))
            queue.append((x, y))

    for x in range(width):
        push_if_bg(x, 0)
        push_if_bg(x, height - 1)
    for y in range(height):
        push_if_bg(0, y)
        push_if_bg(width - 1, y)

    while queue:
        x, y = queue.popleft()
        for nx, ny in ((x - 1, y), (x + 1, y), (x, y - 1), (x, y + 1)):
            if 0 <= nx < width and 0 <= ny < height:
                push_if_bg(nx, ny)

    for x, y in visited:
        pixels[x, y] = (0, 0, 0, 0)

    return rgba


def remove_small_components(image: Image.Image, min_component_pixels: int) -> Image.Image:
    if min_component_pixels <= 0:
        return image

    rgba = image.convert("RGBA")
    alpha = rgba.getchannel("A")
    width, height = rgba.size
    alpha_pixels = alpha.load()
    rgba_pixels = rgba.load()
    visited: set[tuple[int, int]] = set()

    for y in range(height):
        for x in range(width):
            if alpha_pixels[x, y] == 0 or (x, y) in visited:
                continue

            queue: deque[tuple[int, int]] = deque([(x, y)])
            visited.add((x, y))
            component: list[tuple[int, int]] = []

            while queue:
                cx, cy = queue.popleft()
                component.append((cx, cy))
                for nx, ny in ((cx - 1, cy), (cx + 1, cy), (cx, cy - 1), (cx, cy + 1)):
                    if 0 <= nx < width and 0 <= ny < height:
                        if alpha_pixels[nx, ny] == 0 or (nx, ny) in visited:
                            continue
                        visited.add((nx, ny))
                        queue.append((nx, ny))

            if len(component) < min_component_pixels:
                for px, py in component:
                    r, g, b, _ = rgba_pixels[px, py]
                    rgba_pixels[px, py] = (r, g, b, 0)

    return rgba


def normalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
) -> Image.Image:
    rgba = image.convert("RGBA")
    bbox = rgba.getchannel("A").getbbox()
    if bbox is None:
        return Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))

    subject = rgba.crop(bbox)
    if subject.height > subject.width:
        subject = subject.rotate(-90, expand=True, resample=Image.Resampling.BICUBIC)
        rotated_bbox = subject.getchannel("A").getbbox()
        if rotated_bbox is not None:
            subject = subject.crop(rotated_bbox)

    scale = target_width / subject.width
    subject = subject.resize(
        (target_width, max(1, int(round(subject.height * scale)))),
        Image.Resampling.LANCZOS,
    )

    canvas = Image.new("RGBA", (canvas_size, canvas_size), (0, 0, 0, 0))
    offset_x = (canvas_size - subject.width) // 2
    offset_y = (canvas_size - subject.height) // 2
    canvas.alpha_composite(subject, (offset_x, offset_y))
    return canvas


def finalize_product_image(
    image: Image.Image,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> Image.Image:
    transparent = make_transparent_from_borders(image)
    cleaned = remove_small_components(transparent, min_component_pixels)
    return normalize_product_image(cleaned, canvas_size=canvas_size, target_width=target_width)


def save_first_image_part(
    response,
    dst: Path,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    parts = getattr(response, "parts", None)
    if parts is None and getattr(response, "candidates", None):
        parts = response.candidates[0].content.parts

    if not parts:
        raise RuntimeError("Model returned no content parts.")

    for part in parts:
        inline_data = getattr(part, "inline_data", None)
        if inline_data is None and isinstance(part, dict):
            inline_data = part.get("inline_data")

        if inline_data is None:
            continue

        if hasattr(part, "as_image"):
            image = to_pil_image(part.as_image())
            dst.parent.mkdir(parents=True, exist_ok=True)
            finalize_product_image(
                image,
                canvas_size=canvas_size,
                target_width=target_width,
                min_component_pixels=min_component_pixels,
            ).save(dst)
            return

        data = getattr(inline_data, "data", None)
        if data:
            dst.parent.mkdir(parents=True, exist_ok=True)
            with open(dst, "wb") as handle:
                handle.write(data)
            with Image.open(dst) as image:
                processed = finalize_product_image(
                    image,
                    canvas_size=canvas_size,
                    target_width=target_width,
                    min_component_pixels=min_component_pixels,
                )
                processed.save(dst.with_suffix(".png"))
            if dst.suffix.lower() != ".png":
                dst.unlink(missing_ok=True)
            return

    raise RuntimeError("Model returned text only and no edited image.")


def process_image(
    src: Path,
    dst: Path,
    client,
    model: str,
    canvas_size: int,
    target_width: int,
    min_component_pixels: int,
) -> None:
    with Image.open(src).convert("RGBA") as image:
        response = client.models.generate_content(
            model=model,
            contents=[PROMPT, image],
        )

    save_first_image_part(
        response,
        dst,
        canvas_size=canvas_size,
        target_width=target_width,
        min_component_pixels=min_component_pixels,
    )


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description="Cut out product images with Gemini and normalize them to square transparent PNGs."
    )
    parser.add_argument("input_dir", type=Path)
    parser.add_argument("output_dir", type=Path)
    parser.add_argument("--model", default="gemini-2.5-flash-image")
    parser.add_argument("--canvas-size", type=int, default=DEFAULT_CANVAS_SIZE)
    parser.add_argument("--target-width", type=int, default=DEFAULT_TARGET_WIDTH)
    parser.add_argument("--min-component-pixels", type=int, default=DEFAULT_MIN_COMPONENT_PIXELS)
    parser.add_argument("--overwrite", action="store_true")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise SystemExit("Missing GEMINI_API_KEY environment variable.")
    if not args.input_dir.is_dir():
        raise SystemExit(f"Input directory does not exist: {args.input_dir}")
    if args.canvas_size <= 0:
        raise SystemExit("--canvas-size must be positive.")
    if args.target_width <= 0 or args.target_width > args.canvas_size:
        raise SystemExit("--target-width must be positive and no larger than --canvas-size.")
    if args.min_component_pixels < 0:
        raise SystemExit("--min-component-pixels must be >= 0.")

    args.output_dir.mkdir(parents=True, exist_ok=True)
    client = genai.Client(api_key=api_key)

    for src in sorted(args.input_dir.iterdir()):
        if not src.is_file() or src.suffix.lower() not in SUPPORTED_EXTENSIONS:
            continue
        dst = args.output_dir / f"{src.stem}.png"
        if dst.exists() and not args.overwrite:
            print(f"skip {dst}")
            continue
        process_image(
            src,
            dst,
            client,
            args.model,
            canvas_size=args.canvas_size,
            target_width=args.target_width,
            min_component_pixels=args.min_component_pixels,
        )
        print(dst)


if __name__ == "__main__":
    main()

下載附件：product-cutout-normalize.7z

如何呼叫 Google Nano Banana 做圖片去背

Thu, 09 Apr 2026 20:10:48 +0800

這篇文章用一段實際可執行的 Python 腳本，示範如何呼叫 Google 的 Nano Banana 圖像編輯能力來做商品圖去背。

目前這份實作的目標很明確：

讀取一個目錄中的商品圖片
呼叫 Google 圖像模型執行背景移除
對回傳圖片再做一次本地透明背景清理
最終輸出為透明底 PNG

如果你手上已經有一批白底商品圖、耳機圖、線材圖，想快速生成可用於電商的透明背景圖片，這種方式會很直接。

這段程式碼做了什麼

這份腳本主要分成 4 個部分：

定義提示詞，讓模型知道要執行「去背景、保留主體、不要加陰影」
呼叫 google-genai 的圖像生成介面
從模型回應中提取圖片結果
再用本地邏輯把邊緣淺色背景轉成透明，減少殘邊

也就是說，它不是單純把圖片丟給模型就結束，而是把「模型編輯 + 本地後處理」串起來了。

執行前準備

先安裝依賴：

`1`	`.\.venv\Scripts\python.exe -m pip install google-genai pillow`

如何取得 GEMINI_API_KEY

GEMINI_API_KEY 就是呼叫 Gemini API 時使用的金鑰。根據 Google 官方 quickstart，如果你還沒有 key，可以直接在 Google AI Studio 建立。

取得步驟如下：

打開 Google AI Studio。
登入你的 Google 帳號。
找到 Get API key 或 API keys 頁面。
建立一個新的 API key。
複製產生出來的 key。
把它設定到本地環境變數中，供腳本讀取。

如果頁面中還沒有可用專案，通常需要先完成專案初始化，之後再回到 API Key 頁面建立金鑰。

拿到 key 之後，再設定環境變數：

`1`	`$env:GEMINI_API_KEY="your_api_key"`

如果你用的是 cmd，可以寫成：

`1`	`set GEMINI_API_KEY=your_api_key`

如果你同時設定了 GEMINI_API_KEY 和 GOOGLE_API_KEY，實際執行時通常會優先讀取 GOOGLE_API_KEY，所以建議只保留一個，避免混淆。

目錄結構範例

腳本接收兩個參數：

例如：

images/
  product1.jpg
  product2.png

output/

如何執行

假設腳本檔名是 cutout.py，執行方式如下：

`1`	`.\.venv\Scripts\python.exe .\cutout.py .\images .\output`

如果你想換模型，也可以明確傳參：

`1`	`.\.venv\Scripts\python.exe .\cutout.py .\images .\output --model gemini-2.5-flash-image`

腳本會遍歷輸入目錄中的這些格式檔案：

.jpg
.jpeg
.png
.webp

處理完成後，會在輸出目錄中生成同名的透明底 PNG 檔案。

核心呼叫流程

真正呼叫 Google Nano Banana 的關鍵程式碼在這裡：

response = client.models.generate_content(
    model=model,
    contents=[PROMPT, image],
)

這裡傳入了兩個內容：

一段文字提示詞 PROMPT
一張 PIL.Image

提示詞內容是讓模型把整張商品圖背景移除，只保留主體，並強調幾件事：

保留完整商品
保留細線和線纜細節
清理內部空洞和環形區域
不要新增物體
不要添加陰影

這類提示詞對去背品質影響很大，尤其是耳機線、透明邊緣、空洞區域這類細節。

為什麼還要做一次本地後處理

模型回傳結果後，腳本沒有直接儲存，而是又執行了 make_transparent_from_borders(image)。

這一步的思路是：

從圖片四周邊界開始找淺色背景像素
用廣度優先搜尋把連通的淺色區域全部標記出來
最後把這些區域統一改成透明

這樣做的好處是可以進一步清掉一些殘留白邊、淺灰背景和不夠乾淨的邊緣區域。

判斷「是不是背景」的條件在這裡：

def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35

簡單理解就是：

顏色整體夠亮
RGB 三通道差異不能太大

這比較適合處理白底、淺灰底、接近純色的商品圖背景。

完整原始碼

下面保留目前這份完整原始碼，方便你直接重用或二次修改：

from __future__ import annotations

import argparse
import os
from pathlib import Path
from collections import deque

from PIL import Image

try:
    from google import genai
except ImportError as exc:  # pragma: no cover
    raise SystemExit(
        "Missing dependency: google-genai. Install it with "
        r"'.\.venv\Scripts\python.exe -m pip install google-genai'."
    ) from exc


PROMPT = (
    "Remove the entire background from this product photo and return only the product "
    "on a fully transparent background as a PNG. Keep the full product intact, preserve "
    "thin cable details, clean the inner loops and holes, and do not add any new objects "
    "or shadows."
)


def is_light_background_pixel(r: int, g: int, b: int) -> bool:
    brightness = (r + g + b) / 3
    spread = max(r, g, b) - min(r, g, b)
    return brightness >= 170 and spread <= 35


def to_pil_image(image_obj) -> Image.Image:
    if isinstance(image_obj, Image.Image):
        return image_obj
    pil_image = getattr(image_obj, "_pil_image", None)
    if isinstance(pil_image, Image.Image):
        return pil_image
    as_pil = getattr(image_obj, "pil_image", None)
    if isinstance(as_pil, Image.Image):
        return as_pil
    raise TypeError(f"Unsupported image object type: {type(image_obj)!r}")


def make_transparent_from_borders(image: Image.Image) -> Image.Image:
    rgba = image.convert("RGBA")
    width, height = rgba.size
    pixels = rgba.load()

    visited: set[tuple[int, int]] = set()
    queue: deque[tuple[int, int]] = deque()

    def push_if_bg(x: int, y: int) -> None:
        if (x, y) in visited:
            return
        r, g, b, _ = pixels[x, y]
        if is_light_background_pixel(r, g, b):
            visited.add((x, y))
            queue.append((x, y))

    for x in range(width):
        push_if_bg(x, 0)
        push_if_bg(x, height - 1)
    for y in range(height):
        push_if_bg(0, y)
        push_if_bg(width - 1, y)

    while queue:
        x, y = queue.popleft()
        for nx, ny in ((x - 1, y), (x + 1, y), (x, y - 1), (x, y + 1)):
            if 0 <= nx < width and 0 <= ny < height:
                push_if_bg(nx, ny)

    for x, y in visited:
        pixels[x, y] = (0, 0, 0, 0)

    return rgba


def save_first_image_part(response, dst: Path) -> None:
    parts = getattr(response, "parts", None)
    if parts is None and getattr(response, "candidates", None):
        parts = response.candidates[0].content.parts

    if not parts:
        raise RuntimeError("Model returned no content parts.")

    for part in parts:
        inline_data = getattr(part, "inline_data", None)
        if inline_data is None and isinstance(part, dict):
            inline_data = part.get("inline_data")

        if inline_data is None:
            continue

        if hasattr(part, "as_image"):
            image = to_pil_image(part.as_image())
            dst.parent.mkdir(parents=True, exist_ok=True)
            make_transparent_from_borders(image).save(dst)
            return

        data = getattr(inline_data, "data", None)
        mime_type = getattr(inline_data, "mime_type", "")
        if data:
            dst.parent.mkdir(parents=True, exist_ok=True)
            with open(dst, "wb") as handle:
                handle.write(data)
            with Image.open(dst) as img:
                processed = make_transparent_from_borders(img)
                processed.save(dst.with_suffix(".png"))
            if dst.suffix.lower() != ".png":
                dst.unlink(missing_ok=True)
            return

    raise RuntimeError("Model returned text only and no edited image.")


def process_image(src: Path, dst: Path, client, model: str) -> None:
    with Image.open(src).convert("RGBA") as image:
        response = client.models.generate_content(
            model=model,
            contents=[PROMPT, image],
        )
    save_first_image_part(response, dst)


def main() -> None:
    parser = argparse.ArgumentParser(description="Use Nano Banana / Gemini image editing to cut out product images.")
    parser.add_argument("input_dir", type=Path)
    parser.add_argument("output_dir", type=Path)
    parser.add_argument("--model", default="gemini-2.5-flash-image")
    args = parser.parse_args()

    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise SystemExit("Missing GEMINI_API_KEY environment variable.")

    client = genai.Client(api_key=api_key)
    exts = {".jpg", ".jpeg", ".png", ".webp"}

    for src in sorted(args.input_dir.iterdir()):
        if not src.is_file() or src.suffix.lower() not in exts:
            continue
        dst = args.output_dir / f"{src.stem}.png"
        process_image(src, dst, client, args.model)
        print(dst)


if __name__ == "__main__":
    main()

適合繼續優化的地方

如果你準備把這段腳本繼續用於批次生產，後面還可以補這些能力：

增加失敗重試，避免單張圖片報錯後整批中斷
記錄日誌，方便定位是哪張圖處理失敗
把不同背景閾值做成可配置化
支援遞迴掃描子目錄
增加原圖與結果圖的對比預覽

小結

如果你只想快速理解「怎麼呼叫 Google Nano Banana 做去背」，其實核心就三步：

安裝 google-genai 和 Pillow
設定 GEMINI_API_KEY
用 client.models.generate_content() 傳入提示詞和圖片

而這份程式碼的價值在於，它不只是呼叫模型，還補上了透明背景後處理，更適合直接拿去做商品圖去背任務。