# OG Image Generation

**Last Updated:** 2026-02-17

Full workflow for generating Open Graph images with pixel-perfect consistency.

## Overview

| Method | Speed | Consistency | Use When |
|--------|-------|-------------|----------|
| **Playwright (HTML template)** | ~1 sec/image | High (deterministic) | Default; always prefer |
| **Gemini API** | ~5–15 sec/image | Medium (AI variance) | Fallback when Playwright unavailable |
| **Hybrid (Gemini visuals)** | ~8–25 sec total (4 workers) | Medium (AI variance) | Cooler, AI-generated right-panel illustrations; parallelized |

## Playwright Pipeline (Primary)

### Dependencies

```bash
pip install playwright Pillow
playwright install chromium
```

### Generate All Images

```bash
python3 v2/scripts/og-images/generate-og-images.py --all
```

### Generate Specific Types

```bash
python3 v2/scripts/og-images/generate-og-images.py --type=tools --type=comparison --type=template
python3 v2/scripts/og-images/generate-og-images.py --type=tools-index --type=product-nano-ai --type=product-mobile-app --type=content-whitepaper --type=paid-lead --type=product-updates --type=lohnabrechnung
```

### Comparison Pages (Per-Competitor Images)

One template, headline "{competitor_name} Alternativen" – generates `comparison-{slug}.webp` per competitor. Use `--gemini-visuals` for consistent AI-generated right-panel illustrations:

```bash
python3 v2/scripts/og-images/generate-comparison-og-images.py --gemini-visuals
python3 v2/scripts/og-images/generate-comparison-og-images.py --dry-run
```

Competitor list: `v2/scripts/og-images/competitors-for-og.json`

### Options

- `--all` – Generate all page types

- `--type=NAME` – Generate specific type (can repeat)
- `--dry-run` – Print what would be generated
- `--png` – Save PNG instead of WebP (when Pillow missing)

### File Structure

```
v2/scripts/og-images/
├── og-image-specs.json    # Headlines and visual keys
├── og-template.html       # HTML layout (1200×630)
├── illustrations/         # SVG per page type
│   ├── default.svg
│   ├── product.svg
│   ├── industry.svg
│   ├── partner.svg
│   ├── tools.svg
│   ├── comparison.svg
│   ├── webinar.svg
│   ├── download.svg
│   └── template.svg
├── generate-og-images.py
├── generate-og-image-gemini.py
├── generate-comparison-og-images.py   # Per-competitor comparison images
├── competitors-for-og.json           # Competitor slug/name for comparison batch
├── update-compare-pages-og.py         # One-time: wire compare pages to dynamic OG
├── update-compare-schema-images.py    # Update JSON-LD schema (publisher.logo, Article.image, primaryImageOfPage)
├── validate-og-images.py
└── validate-og-logo.py
```

### Editing Headlines

Edit `v2/scripts/og-images/og-image-specs.json`:

```json
{
  "tools": {
    "headline": "Kostenlose Tools & Rechner",
    "visual": "tools"
  }
}
```

### Editing Illustrations

Edit SVG files in `v2/scripts/og-images/illustrations/`. Use white and `#4D8EF3` at 20–50% opacity. Keep style flat and illustrative (no photorealistic elements).

## Gemini Fallback

Use when Playwright is not available (e.g. CI without browser, one-off experiment).

### Prerequisites

- `GEMINI_API_KEY` (see [GEMINI_API_KEY_LOCAL.md](../../development/GEMINI_API_KEY_LOCAL.md); same resolution as `v2/config/ai-faq-config.php`)
- `pip install requests Pillow`

### Generate

```bash
python3 v2/scripts/og-images/generate-og-image-gemini.py --type=comparison
python3 v2/scripts/og-images/generate-og-image-gemini.py --type=tools --type=template --dry-run
```

### Limitations

- AI may produce slight color/logo variance
- Generates at 16:9, then crops to 1200×630
- Slower than Playwright

## Hybrid Pipeline (Gemini Visuals)

Use Gemini to generate **right-panel illustrations only**, then composite onto the HTML-rendered left panel. Produces cooler, more dynamic visuals than static SVGs.

### Flow (Reference Style – White Right Panel)

1. **HTML left panel** – Playwright renders headline + logo on blue (#4D8EF3); right panel empty, **white background**.
2. **Gemini right panel** – Generates 420×630 illustration on **pure white background** – isometric 3D, light blue (#4D8EF3) outlines/fills, soft gray drop shadows.
3. **Composite** – Paste directly onto white right 420px (no chroma, no rembg).
4. **Output** – Save as WebP.

Matches reference: blue left, white right, isometric 3D illustrations with soft shadows. No background removal.

### Prerequisites

- `GEMINI_API_KEY` (see [GEMINI_API_KEY_LOCAL.md](../../development/GEMINI_API_KEY_LOCAL.md); same resolution as `v2/config/ai-faq-config.php`)
- `pip install playwright Pillow requests`

### Generate with Gemini Visuals

```bash
# All 9 images, 4 parallel workers (default)
python3 v2/scripts/og-images/generate-og-images.py --all --gemini-visuals

# Specific types, 2 workers
python3 v2/scripts/og-images/generate-og-images.py --type=tools --type=comparison --gemini-visuals --workers 2
```

### Options

- `--gemini-visuals` – Use Gemini for right-panel illustrations instead of SVG.
- `--workers N` – Parallel workers (default: 4). Speeds up bulk generation.
- `--rembg` – Use rembg for background removal (only when using white-bg prompts; not default).
- `--alpha-matting` – When using `--rembg`, enable alpha matting for softer edges (slower).

### Best Practices

1. **White right panel:** Default: blue left, white right. Prompts request pure white background; no chroma/rembg.
2. **Prompts:** Per-type prompts in `generate-og-image-gemini.py` (`VISUAL_ONLY_PROMPTS`). Style: isometric 3D, light blue outlines/fills, soft gray drop shadows – matches reference.
3. **Aspect ratio:** Right panel is 420×630 (2:3). Gemini generates at 2:3.
4. **Reference style:** Isometric 3D, detailed elements, soft shadows, substantial. Override model via `GEMINI_IMAGE_MODEL=gemini-3-pro-image-preview` for higher quality.

### Prompt Design Principles

When editing `VISUAL_ONLY_PROMPTS` or `VISUAL_DESCRIPTIONS` in `generate-og-image-gemini.py`:

- **Minimal text:** Explicitly instruct "NO text", "iconography only", "no numbers or labels". Use abstract shapes instead of labeled elements (e.g. document icon, not "PDF").
- **German audience:** Headlines are in German; visuals should be universally understandable. No need for German text in visuals – avoid text altogether.
- **Visual appeal:** Add "cool", "interesting", "engaging", "dynamic" to encourage non-generic output. Specify composition (e.g. "cohesive layout", "balanced").
- **Consistency:** All prompts share `REFERENCE_STYLE` – isometric 3D, light blue (#4D8EF3), white, soft shadows. Keep subject descriptions aligned with this style.

## Validation

After generation:

```bash
python3 v2/scripts/og-images/validate-og-images.py
python3 v2/scripts/og-images/validate-og-logo.py
```

- **validate-og-images.py:** Dimensions 1200×630, left-panel color ≈ #4D8EF3, file size.
- **validate-og-logo.py:** Logo visibility (samples logo region 56–176×48–80px for white/light pixels; matches template padding).

## Troubleshooting

### Playwright: "Executable doesn't exist"

```bash
playwright install chromium
```

### Fonts not loading

The HTML template uses relative paths to `src/fonts/`. Ensure the script runs from repo root and the temp HTML is written to `v2/scripts/og-images/` (so paths resolve correctly).

### Logo not visible

Verify `v2/img/affiliate/ordio-logo.svg` exists. The template uses `../../img/affiliate/ordio-logo.svg`; temp HTML must be in `v2/scripts/og-images/` so the path resolves. Run `validate-og-logo.py` to check logo region.

### Pillow not installed

Script falls back to PNG output. Install: `pip install Pillow`

### Gemini API 429 / rate limit

Wait and retry. Use Playwright for bulk generation instead.

## Figma Export Alternative

For design-led updates, export from Figma at 1200×630, then:

1. Export as PNG
2. Convert to WebP: `cwebp -q 85 input.png -o output.webp`
3. Save to `v2/img/og/{type}.webp`
4. Run `validate-og-images.py`

## References

- [OG_IMAGE_GUIDE.md](OG_IMAGE_GUIDE.md) – Specs and usage
- [OG_IMAGE_ASSET_CHECKLIST.md](OG_IMAGE_ASSET_CHECKLIST.md) – Asset inventory
- [DBushell: Generate OG images with Playwright](https://dbushell.com/2024/11/15/generate-open-graph-images-with-playwright/)