Amazon Product Image Generator

---
name: amazon-product-image-generator
description: Generate Amazon listing image sets from product reference images using a two-step AI-driven workflow. Use when the user wants product image analysis, Amazon image planning, prompt building, queued/batch image generation, local saving, retry, breakpoint resume, SQLite task tracking, or worker-based image generation for Amazon marketplace assets.
---

# Amazon Product Image Generator

Generate professional Amazon listing/A+ image sets from product photos.
The workflow is **two-step AI-driven analysis + prompt building**, followed by
queue-based image generation.

## Core Workflow (Two-Step AI-Driven)

```text
Step 1: Visual Recognition (AI reads product image -> detailed text description)
Step 2: Product Analysis + Prompt Strategy (AI analyzes -> per-image Chinese prompts)
Step 3: Output job JSON -> submit to worker -> generate images
```

The AI itself performs Steps 1 and 2. This is faster and higher quality than
delegating analysis to an external API call, because the AI is smarter than a
flash model and eliminates a network round-trip. Python scripts handle only the
image generation infrastructure (queue, worker, retry, saving).

---

## Step 1: Visual Recognition

**Goal**: Convert the product image into a comprehensive text description.

The AI reads the product image using its vision capability (Read tool) and
produces a detailed description covering **ALL visual information** (excluding
any text/copy in the image):

- Product shape, silhouette, outline
- Color(s), exact shades
- Material(s) and surface finish (matte/glossy/textured/transparent)
- Construction details, seams, joints
- Components, parts, accessories visible
- Ports, openings, buttons, switches
- Logo, brand markings, labels (describe visually, do not transcribe copy)
- Proportions, scale impression
- Texture patterns (weave, grain, brush, etc.)
- Any other visible physical details

**Critical**: This description becomes the "product visual identity" that
ensures all generated images preserve the exact same product. It must be
detailed enough that an image model can reproduce the product faithfully.

**Output**: A text block of 200-400 words saved as `visual_description` in the
analysis output.

### Step 1 Prompt Template

When analyzing the product image, use this internal prompt:

```
仔细观察这张产品图片，详细描述图片中的所有视觉信息（不要描述图片中的文字/文案内容）。

请按以下维度逐一描述：

1. 产品形状与轮廓：整体形状、侧面轮廓、立体感
2. 颜色：主色、辅色、 exact 色调描述
3. 材质与表面处理：材质类型、表面光泽度（哑光/亮面/磨砂/透明）、触感推断
4. 结构细节：接缝、连接处、分层结构
5. 组件与配件：可见的所有部件、零件
6. 开孔与按键：接口类型、按键位置、开关
7. Logo 与标记：品牌标识位置和样式（仅描述视觉，不抄录文字）
8. 比例与尺寸感：整体大小印象、各部分比例关系
9. 纹理与图案：表面纹理、花纹、编织方式等
10. 其他细节：任何其他可见的物理特征

输出格式：直接输出详细描述文字，不需要分点编号，用流畅的描述性段落。
```

---

## Step 2: Product Analysis + Prompt Strategy

**Goal**: Analyze the product and generate per-image Chinese prompts.

Using the visual description from Step 1 + user-provided product info + market +
copy language, the AI:

1. **Analyzes the product**:
   - Core selling points and differentiation
   - Target audience and market
   - Customer pain points and purchase objections
   - Realistic use scenarios
   - Category-specific Amazon visual conventions
   - How to visually express each selling point

2. **Plans the image set**:
   - First image must be the main/hero image
   - Each subsequent image covers ONE core selling point
   - One selling point = one image (no overlap)
   - Prefer visual expression over text-heavy infographics
   - Auto-adapt to product category (electronics, home, kitchen, pet, etc.)

3. **Writes per-image prompts** following `references/prompt_strategy.md`:
   - Each prompt is a complete Chinese image generation prompt
   - Each prompt specifies: image type, unique core selling point, scene design,
     product display, photography method, lighting, color, background, people
     (if needed), copy (if needed)
   - All prompts maintain set-wide consistency (product, style, lighting, palette)

**Reference**: See `references/prompt_strategy.md` for the complete prompt
generation template with all 10 image types and planning principles.

### Image Types (auto-selected based on product)

| Type | Purpose |
|------|---------|
| 主图 (Hero) | White background, product hero, Amazon-compliant |
| 场景图 (Lifestyle) | Real use scene, emotional connection |
| 功能规格图 (Feature Infographic) | One feature via visual infographic |
| 核心卖点图 (Benefit) | One core benefit, visual impact |
| 材质细节图 (Detail) | Material, texture, craftsmanship macro |
| 尺寸图 (Dimension) | Size visualization, no invented numbers |
| 对比图 (Comparison) | Product advantage vs alternative |
| 规格参数图 (Specification) | Specs, compatibility, package contents |
| A+ 使用场景图 (A+ Lifestyle) | Brand lifestyle banner |
| A+ 核心卖点图 (A+ Benefit) | Brand core value banner |

Minimum 5 images. Expand to 8-10 when the product has enough distinct selling points.

---

## Step 3: Output Job JSON + Generate

After Steps 1 and 2, the AI outputs a job JSON matching the contract below,
then submits it to the worker for image generation.

### Skill Output Contract

```json
{
  "schema_version": "amazon-image-job/v1",
  "job_id": "job_20260602_brand_product_batch001",
  "market": "US Amazon",
  "created_by": "amazon-product-image-generator",
  "metadata": {
    "visual_description": "Step 1 visual description text...",
    "product_analysis": {
      "selling_points": ["...", "..."],
      "target_audience": ["..."],
      "use_scenes": ["..."],
      "category": "..."
    }
  },
  "tasks": [
    {
      "task_id": "sku_001_hero",
      "product_id": "sku_001",
      "image_id": "hero",
      "image_type": "main_image",
      "prompt": "完整的中文生图提示词...",
      "reference_image": "D:/path/product_001.jpg",
      "save_path": "D:/output/job_001/sku_001/hero.png",
      "filename": "hero.png",
      "metadata": {
        "aspect_ratio": "1:1",
        "purpose": "Amazon主图，纯白背景产品展示",
        "core_selling_point": "产品完整外观",
        "text_policy": "model_renders_text"
      }
    }
  ]
}
```

Required fields:
- Top level: `schema_version`, `job_id`, `tasks`.
- Per task: `prompt`, `image_type`.
- Strongly recommended: `product_id`, `image_id`, `reference_image`, `save_path`.

Each task's `metadata.core_selling_point` must state the single selling point
that image addresses.

---

## Architecture

```text
AI Skill (Step 1 + Step 2)
  -> visual recognition + product analysis + per-image Chinese prompts
  -> generation job JSON
  -> redis_task_submit.py  OR  image_task_submit.py
  -> Redis Stream / SQLite
  -> redis_worker.py  OR  worker.py
  -> Image API key pool + async concurrency + retry
  -> Save local images
  -> redis_result_reader.py  OR  image_result_reader.py
```

Task statuses:

```text
PENDING -> QUEUED -> GENERATING -> DONE
                              -> FAILED
```

---

## Core Scripts

Run scripts from this skill folder.

| Role | Script | Purpose |
|------|--------|---------|
| image-planner (fallback) | `scripts/image_planner.py` | Batch fallback: analyze product image + info via API, output analysis.json + image_plan.json |
| prompt-builder (fallback) | `scripts/prompt_builder.py` | Rebuild prompts from existing analysis.json (batch fallback) |
| image-task-submit | `scripts/image_task_submit.py` | Batch-write image tasks to SQLite without calling the image API |
| local-runner | `scripts/worker.py` | Consume queued tasks with async concurrency, retry, polling, local saving |
| redis-task-submit | `scripts/redis_task_submit.py` | Push Skill job JSON into Redis Stream without calling the image API |
| redis-worker | `scripts/redis_worker.py` | Independent async worker with Redis consumer group, key pool, delayed retry, local saving |
| redis-result-reader | `scripts/redis_result_reader.py` | Read Redis task status, failures, and local result paths |
| image-postprocess | `scripts/image_postprocess.py` | Optional fallback renderer for local text overlays |
| image-result-reader | `scripts/image_result_reader.py` | Read task status and local result paths |

**Primary mode**: The AI directly produces the job JSON (Steps 1 + 2) and
submits it. Scripts are infrastructure only.

**Batch fallback mode**: For 50+ products where individual AI analysis is
impractical, use `image_planner.py` to call the analysis API per product.

---

## Workflow Examples

### Single Product (Primary - AI-Driven)

1. **AI reads product image** and writes visual description (Step 1)
2. **AI analyzes product** and writes per-image prompts (Step 2)
3. **AI outputs job JSON** and saves it

```bash
# Save the AI-generated job JSON to a file, then:
python scripts/redis_task_submit.py --job-json "job_001.json"
python scripts/redis_worker.py --once
python scripts/redis_result_reader.py --job-id "job_001"
```

Or with SQLite mode:

```bash
python scripts/image_task_submit.py --plan "image_plan.json" --reference "product.jpg"
python scripts/worker.py --once --reset-incomplete
python scripts/image_result_reader.py --status DONE
```

### Batch Products (Fallback - API-Driven)

```bash
python scripts/image_planner.py --input "path/to/product.jpg" --product-info "details" --market "US Amazon"
python scripts/image_task_submit.py --plan "path/to/image_plan.json" --reference "path/to/product.jpg"
python scripts/worker.py --reset-incomplete
```

### High-Throughput Redis Flow

1. Start Redis:

```bash
docker compose -f docker-compose.redis.yml up -d
```

2. Install worker dependencies:

```bash
pip install -r requirements-redis-worker.txt
```

3. AI produces job JSON, then:

```bash
python scripts/redis_task_submit.py --job-json "job_001.json"
python scripts/redis_worker.py
```

4. Read results:

```bash
python scripts/redis_result_reader.py --job-id "job_001"
python scripts/redis_result_reader.py --status FAILED
```

---

## Default Stability Rules

- Run locally. Save images locally.
- Default storage root: `~/Desktop/amazon_product_image_generator`.
- Default image path: `storage/images/task_xxx/<image_type>.png`.
- Default SQLite DB: `~/Desktop/amazon_product_image_generator/tasks.sqlite3`.
- Recommended batch concurrency: `MAX_CONCURRENT=2`. Increase only after provider is stable.
- Timeout per task attempt: `GENERATION_TIMEOUT=90`.
- Retry per task: `MAX_RETRIES=3`.
- Backoff: `2s`, `4s`, `8s`.
- Model fallback is automatic: 429/403/no-image triggers next model.
- Model cooldown is persisted to `model_health.json`.
- A successful model is promoted to front of in-memory model order.
- Request pacing with `REQUEST_SPACING_SECONDS` and `PER_MODEL_SPACING_SECONDS`.
- Reference images are compressed before API submission.
- Re-submitting the same plan uses stable task IDs. Existing DONE/queued tasks are skipped; FAILED tasks are reset to PENDING.
- If a saved file already exists, the worker marks the task DONE.
- If all models are cooling, the worker defers the task.
- Use `worker.py --reset-incomplete` after interruption.
- For `gpt-image-2`, prompts are complete Amazon graphic prompts: the model renders product, layout, headline, subline, and callouts directly.
- Set `GENERATE_TEXT_IN_MODEL=false` and `LOCAL_TEXT_OVERLAY=true` only when the model cannot reliably render text.
- The planner must create differentiated image types, not repeated product arrangements.
- For 100-product batches, use Redis worker mode. Start with `WORKER_MAX_CONCURRENT=12` and `PER_KEY_MAX_CONCURRENT=2`.
- Configure `IMAGE_API_KEYS` as a comma-separated key pool.

---

## API Configuration

Copy `.env.example` to `.env` and fill in your API credentials:

```env
# Required
IMAGE_API_BASE_URL=https://your-api-provider.com/v1
IMAGE_API_KEY=sk-XXX
IMAGE_MODEL=gpt-image-2

# Optional (defaults shown)
# IMAGE_ANALYSIS_MODEL=gemini-3.1-flash-image-preview
# MAX_CONCURRENT=2
# GENERATION_TIMEOUT=90
# GENERATE_TEXT_IN_MODEL=true
# IMAGE_OUTPUT_SIZE=2000
```

---

## Key Quality Rules

1. **One selling point per image** — never pack multiple features into one image.
2. **Visual-first** — express selling points through imagery, not text blocks.
3. **Product fidelity** — all images must preserve the exact product from the reference image.
4. **Set consistency** — same lighting, palette, style, typography across all images.
5. **Category adaptation** — auto-adjust photography style to product category.
6. **Amazon compliance** — no fake certifications, no invented specs, no watermarks.
7. **Chinese prompts** — all image generation prompts are written in Chinese for best results with image models.
8. **Copy language** — visible text in images uses the user-specified language.