image-ad-clone

Files (1)

• SKILL.md

SKILL.md (first lines)

# image-ad-clone (KIE.ai)

Take an existing image ad and turn it into a reusable, parameterizable prompt template that gets appended to the shared **37-template image-ad library**. The template is validated by round-tripping through one of the KIE.ai image-ad generators — **ChatGPT Image 2** (typography / UI-mimicry templates) or **Nano Banana** (photoreal / lifestyle / multi-reference templates).

This skill replaces the older Uni1-locked `image-ad-clone` (which only worked with Luma uni-1). It's backend-agnostic: at Phase 1 the agent asks you (or auto-detects from the reference) whether to validate against gpt-image-2 or Nano Banana, then routes through the matching generator script in this repo.

## Read order

1. **This file** — KIE-specific generator paths, model-choice decision, what's locked at the per-repo layer.
2. **[shared/skills/image-ad-clone/prompting/guide.md](../../shared/skills/image-ad-clone/prompting/guide.md)** — the full model-agnostic 10-phase workflow.
3. **[shared/skills/image-ad-prompting/prompting/template-format.md](../../shared/skills/image-ad-prompting/prompting/template-format.md)** — entry skeleton.
4. **[shared/skills/image-ad-prompting/prompting/prompt-library.md](../../shared/skills/image-ad-prompting/prompting/prompt-library.md)** — destination for the new entry.

## Hard rules

Inherits all 6 hard rules from the shared guide. Plus per-repo:

7. **Backend is one of: ChatGPT Image 2 (via KIE's dedicated `/gpt4o-image/generate` endpoint) OR Nano Banana (via `/jobs/createTask`).** Never uni-1.

## Picking the right backend in Phase 1

Pick by what the reference ad is showing — most templates fall into one clear bucket.

**Use `chatgpt-image-ad` when the reference is:**
- Typography-heavy / UI mimicry (Apple Notes lists, fake Google search, fake Slack threads, ChatGPT-conversation ads, iMessage screenshots, comparison tables, fake AirDrop dialogs, Hinge-style cards, calendar UI, weather forecast UI, magazine masthead)
- Brutalist / editorial typography heros
- Dense small text inside UI elements

**Use `nano-banana-image-ad` when the reference is:**
- Photoreal handheld objects (whiteboards, napkins, sticky notes, letter boards, scratch-off tickets)
- Aspirational lifestyle photography (sunset, kitchen at golden hour, OOH / transit)
- Multi-image reference blending (logo + product + style + character all in one)
- Clay / claymation / Pixar-adjacent textures

**If the reference straddles both**, clone twice (once per backend) and ship the template with `Model notes` saying which renders cleaner. The agent offers this in Phase 8.

If the user explicitly says "clone this with gpt-image-2" or "with Nano Banana", honor that.

## Dependencies

This skill uses the matching generator script in the SAME repo:
- For gpt-image-2 validation: `skills/chatgpt-image-ad/scripts/generate_image.py` (hits KIE's dedicated `/api/v1/gpt4o-image/generate` endpoint)
- For Nano Banana validation: `skills/nano-banana-image-ad/scripts/generate_image.py` (hits `/jobs/createTask` with `nano-banana-2`/`-pro`/`-edit`)

Fail Phase 1 with a fix-it message if neither generator is installed in this repo.

Also required:
- `.env` with `KIE_API_KEY`
- Reference ad image hosted at a **public URL** (KIE has no presigned-upload flow). The agent will stop and ask for hosting if you pass a local path with no host configured in `MASTER_CONTEXT.md`.
- Python 3.12+

## Where this skill's generator lives

When the [shared guide](../../shared/skills/image-ad-clone/prompting/guide.md) Phase 1 tells you to locate the companion generator, look here in order based on the model choice:

For gpt-image-2:
1. `~/.claude/skills/chatgpt-image-ad/scripts/generate_image.py`
2. `<repo>/skills/chatgpt-image-ad/scripts/generate_image.py`
3. If neither: stop and ask the user to install `chatgpt-image-ad` first.

For Nano Banana:
1. `~/.claude/skills/nano-banana-image-ad/scripts/generate_image.py`
2. `<repo>/skills/nano-banana-image-ad/scripts/generate_image.py`
3. If neither: stop and ask the user to install `nano-banana-image-ad` first.

## Reference image hosting

KIE only accepts public URLs as references. Before any generation in this workflow:

1. The reference ad image must already be at a public URL, OR
2. The user has configured an image-hosting strategy in `MASTER_CONTEXT.md` under "Image hosting" (R2 / S3 / Cloudinary / imgur / 0x0.st / etc.)

If neither, **stop at Phase 1** and ask the user how to host. Record their answer in `MASTER_CONTEXT.md` for future runs.

The generator scripts HEAD-probe the URL before submitting; pass `--skip-url-check` if your host blocks HEAD requests.

## Aspect ratio mapping per backend

Each KIE backend has different native aspect-ratio support. When measuring the original ad's aspect (Phase 2):

**`chatgpt-image-ad` (KIE `/gpt4o-image/generate`):** accepts only `1:1`, `3:2`, `2:3`.
- `4:5` ad → use `2:3` (taller; document the map)
- `1.91:1` ad → use `3:2`
- `9:16` / `16:9` ads → NOT supported on this backend; consider Nano Banana for those

**`nano-banana-image-ad` (KIE `/jobs/createTask`):** accepts the full Meta ratio set — `1:1`, `4:5`, `5:4`, `2:3`, `3:2`, `9:16`, `16:9`, `3:4`, `4:3`, `21:9`. **Default to `4:5` for Meta feed-portrait** — KIE Nano Banana renders it natively.

If your reference ad's native ratio isn't supported by the backend you want, the choice is:
1. Switch backends (most ratios work on Nano Banana)
2. Render at the closest supported ratio and document the fallback in the `Aspect ratio:` field
3. (For very narrow / very tall ads) Consider the Arcads repo's `image-ad-clone` instead

## Workflow phases (model-agnostic, see shared guide for full detail)

1. **Phase 1: Preflight + model choice + hosting check.** Reference URL reachable; `.env` has `KIE_API_KEY`; both generators detected. **Ask the user which model to validate against** (or auto-detect from the reference). Confirm reference image is at a public URL.
2. **Phase 2: Visual analysis.** Describe the reference structurally — aspect ratio, format type, layout, typography, color palette, photography style, every text string verbatim, decorative elements, chrome to strip.
3. **Phase 3: Draft v1 prompt** (brand-specifics intact).
4. **Phase 4: Generate with reference** using the matching generator script. Pass `--image-url <reference_url>` and the matched aspect ratio.
5. **Phase 5: Compare and iterate.** Refine prompt based on deltas. Cap 4 iterations.
6. **Phase 6: Generalize into placeholders.**
7. **Phase 7: Test the generalized template** against a DIFFERENT brand (need a different brand's product photo hosted at a public URL).
8. **Phase 8: Cross-model validation (recommended).** Run the same template through the OTHER backend in this repo. Document deltas in the `Model notes` block.
9. **Phase 9: Document the template** using `template-format.md`. Required `Model notes` for both backends.
10. **Phase 10: Save and confirm.** Append to `shared/skills/image-ad-prompting/prompting/prompt-library.md`.

## Iteration directory layout

```
<cwd>/iterations/clone-2026-05-26/
  T40-lifestyle-hero/
    prompt.txt
    v1.png, v2.png, …                # against the source ref (chosen backend)
    test-fill-v1.png, …              # Phase 7 generalization test
    cross-{other-backend}/v1.png     # Phase 8 cross-model validation
    notes.md
```

## See also

From harperaa/hermes-plugin-short-form, MIT.

More from harperaa/hermes-plugin-short-form