nano-banana-image-ad

nano-banana-image-ad (Arcads)

Generate one or more standalone Meta ad image creatives via Arcads' POST /v2/images/generate with the Nano Banana model family (default nano-banana-2). Hands the image paths off to your Meta-ad-builder skill — this skill does not upload to Meta itself.

Read order

1. This file — Arcads-specific endpoint, auth, presigned upload flow, workflow phases.
2. shared/skills/nano-banana-image-ad/prompting/guide.md — model-specific prompting (what Nano Banana is good/bad at, when to switch to gpt-image-2).
3. shared/skills/image-ad-prompting/prompting/prompt-library.md — 30+ validated templates with per-model notes.
4. shared/skills/image-ad-prompting/prompting/safety-suffixes.md — the 3 always-on guards.
5. scripts/generate_image.py — the helper script (Python stdlib only).

Hard rules — never relax

1. Model is in the Nano Banana family. The script accepts nano-banana-2 (default), nano-banana-pro (Gemini 3 Pro Image, higher cost / locked identity), nano-banana-edit (inpaint-focused), or nano-banana (legacy). Anything else is refused. If the user asks for gpt-image-2, point them at chatgpt-image-ad.
2. No platform/screenshot chrome in output. NO_CHROME_SUFFIX is always on (override only with --allow-chrome).
3. Edge-safe + glyph-safety suffixes always on unless --no-safe-zone is explicit.
4. Max 14 reference images. Hard Arcads cap for Nano Banana. Script enforces.
5. No Meta upload from this skill. Image generation only. The user has a separate ad-builder skill in their stack — hand off via filesystem paths.
6. Always present a credit-cost estimate before generating. Each Nano Banana call is one image; multiply by --n. nano-banana-pro costs more than nano-banana-2 — surface the per-model rate from logs/arcads-api.jsonl.

Prerequisites

• .env containing ARCADS_BASIC_AUTH (preferred) OR ARCADS_API_KEY
• Optional: PRODUCT_ID, PROJECT_ID in .env for session-folder organization
• Reference images on local disk. The script handles the Arcads presigned-upload flow internally.

Configuration

• Base URL: https://external-api.arcads.ai (or ARCADS_BASE_URL).
• Auth: HTTP Basic. The script prefers a pre-encoded ARCADS_BASIC_AUTH; falls back to encoding ARCADS_API_KEY.
• Endpoint: POST /v2/images/generate; poll GET /v1/assets/{id} until status: generated.
• Reference uploads: POST /v1/file-upload/get-presigned-url returns {presignedUrl, filePath}; PUT bytes to presignedUrl; pass the filePath in referenceImages. Single-use — re-uploaded fresh per variant by the script.

Generation modes

Mode	When to use	Required	Optional
image (default)	Brand-new ad image.	--prompt, --aspect-ratio	--image-ref (up to 14)
image_edit	Modify a --source image.	--prompt, --source	--image-ref (up to 14)

Supported aspect ratios

1:1, 16:9, 9:16. Only these three are accepted by Arcads' /v2/images/generate endpoint (the same endpoint serves gpt-image-2 and Nano Banana — same ratio constraints). Templates in the shared library that use 2:3, 4:5, 3:2, etc. won't render at their native ratio on this backend — fall back to 1:1 and post-crop, or use the KIE nano-banana-image-ad sibling which supports the full Meta ratio set natively via the /jobs/createTask endpoint.

Model variants (--model)

• nano-banana-2 (default) — Gemini 2.5 Flash Image. The standard. Use for most templates.
• nano-banana-pro — Gemini 3 Pro Image. Use for hero stills, character continuity across runs, material-realism critical shots (claymation, Pixar, premium product photography). Costs more credits.
• nano-banana-edit — inpaint-focused. Use only with --mode image_edit for tight masked edits (swap background, change object color).
• nano-banana — legacy. Use only if the user explicitly asks; new work should use nano-banana-2.

Ask the user which variant they want before the first generation in a session if the value isn't already set in MASTER_CONTEXT.md. Default to nano-banana-2.

Workflow

Phase 1: Preflight

1. .env exists with credentials.
2. (Optional) arcads-external-api session folder set up.
3. Health-check: curl -sf -H "$AUTH" "$BASE_URL/v1/products" returns 200.

Phase 2: Gather inputs

Collect: seed prompt, mode, source (if edit), reference paths (up to 14), variant count, aspect ratio, model variant.

Phase 3: Prompt rewrite

Read shared/skills/image-ad-prompting/prompting/prompt-library.md. If the user's brief matches a template, check the Model notes block — only proceed if nano-banana is marked clean, preferred, or strong. If gpt-image-2 is preferred, suggest switching skills.

Fill {placeholders} and show the user the rewritten prompt. Ask for approval before generating.

For fresh prompts (no template match), follow the structure in shared/skills/nano-banana-image-ad/prompting/guide.md § Phase 3b — lean on Nano Banana strengths (named reference roles, lighting specifics, material specifics).

Phase 4: Credit cost confirmation (MANDATORY)

Present the estimated credit cost (read from logs/arcads-api.jsonl for matching past calls). Surface the model variant prominently: nano-banana-pro costs more than nano-banana-2. Wait for explicit confirmation.

Phase 5: Generate

~/.claude/skills/nano-banana-image-ad/scripts/generate_image.py \
  --prompt "<rewritten>" \
  --aspect-ratio <ratio> \
  --n <N> \
  --image-ref <product.png> \
  [--image-ref <character.png>] \
  [--image-ref <style.png>] \
  --out ./generated \
  --env-file .env

# For higher-stakes hero shots:
~/.claude/skills/nano-banana-image-ad/scripts/generate_image.py \
  --model nano-banana-pro \
  --prompt "<rewritten>" \
  --aspect-ratio <ratio> \
  --n <N> \
  --image-ref <product.png> \
  --out ./generated \
  --env-file .env

# For an edit run (inpaint):
~/.claude/skills/nano-banana-image-ad/scripts/generate_image.py \
  --mode image_edit \
  --model nano-banana-edit \
  --prompt "<edit-instruction>" \
  --source <existing.png> \
  [--image-ref <guidance.png>] \
  --n <N> \
  --out ./generated \
  --env-file .env

Each line on stdout is one JSON variant (variant, path, asset_id, width, height, prompt, mode, aspect_ratio, model).

Log each call to logs/arcads-api.jsonl with the model variant, ref count, and returned asset_ids.

Phase 6: Visual QA (MANDATORY)

For each completed variant, read the image and inspect for:

• Garbled small text (the main Nano Banana weakness)
• Extra fingers / wrong limb count (common Gemini-family failure)
• Wordmark drift (always pass brand wordmarks as --image-ref to mitigate)
• Character identity drift across variants (use nano-banana-pro to lock identity if it matters)

If defects: regenerate with a revised prompt that explicitly corrects the issue (see shared/skills/nano-banana-image-ad/prompting/guide.md § Retry mode). Cap at 2 retries per variant.

Phase 7: Confirm and hand off

Show all paths to the user. Ask "Use all / use these specific ones / regenerate / cancel."

Selected variants are ready for your Meta-ad-builder skill. Print the paths.

Optionally, write the selected paths to ./generated/run-<ts>.jsonl for downstream consumption.

Out of scope — fail clearly

• Meta upload — different skill in your stack.
• ChatGPT Image 2 / gpt-image-2 generation — use chatgpt-image-ad.
• Video, carousel, DCO ads — image only.
• Ad copy writing — different skill.
• Editing the shared prompt library — use image-ad-clone (asks which backend at Phase 1).

Common errors

• 401/403 → fix .env.
• 422 validation/moderation → tighten prompt; check aspectRatio is in supported set; check --n ≤ 5.
• 500 UNKNOWN_ERROR → usually a stale presigned filePath. The script re-uploads per variant; if persistent, file an issue with the asset_id.

Files this skill owns

• ~/.claude/skills/nano-banana-image-ad/SKILL.md — this file
• ~/.claude/skills/nano-banana-image-ad/scripts/generate_image.py — Arcads Nano Banana caller

See also

• shared/skills/nano-banana-image-ad/prompting/guide.md — model-specific prompting
• shared/skills/image-ad-prompting/prompting/prompt-library.md — shared template library
• image-ad-clone skill — single backend-agnostic skill that reverse-engineers an existing ad into a reusable library entry
• arcads-external-api skill — underlying Arcads conventions
• chatgpt-image-ad skill — sibling skill for typography-heavy / UI-mimicry templates