Aaa Image Editing

AAA Image Editing v2.0

The umbrella skill for image work that requires editing a real photo (identity preservation) vs generating from scratch. These are fundamentally different tasks.

CRITICAL DISTINCTION: Generation ≠ Editing

The #1 mistake (corrected by F13 2026-08-12): using a generation model when the user provided a real photo and wants to "place this person in a scene." The model will fabricate a different person. Always classify first.

The Nano Banana Family (verified live 2026-08-13)

Google's native image editing models, all accessible via our API key. All generated images include an invisible SynthID watermark.

Model Selection Decision Tree

User provides real photo + wants edit?
  ├─ Quick iteration (try 3-5 variants)? → NB2-Lite or NB (fastest, cheapest)
  ├─ Single edit, identity matters? → NB2 (best all-rounder)
  ├─ Hero asset, text in image, 4K needed? → NB-Pro
  └─ Ensemble (run multiple, pick best)? → NB + NB2 + NB-Pro in parallel

Text-only generation (no reference photo)?
  ├─ Fast/cheap? → NB2-Lite
  ├─ Best quality? → NB2
  └─ Complex composition? → NB-Pro

Pricing (as of June 2026)

Endpoints and Auth (verified 2026-08-13)

Gemini Nano Banana (ALL variants via same key)

• Script: /root/HERMES/scripts/gemini-image.py
• Key: $GEMINI_API_KEY from /root/.secrets/kunci-mas.env
• API: https://generativelanguage.googleapis.com/v1beta
• Models: gemini-3.1-flash-lite-image, gemini-3.1-flash-image, gemini-3-pro-image, gemini-2.5-flash-image
• Semantic Mask: --semantic-mask "man's face, physique, pose" — auto-prepends preservation clause
• All 4 models confirmed HTTP 200 on 2026-08-13

Qwen Bailian PAYG (alternative for editing)

• URL: https://ws-wlab8klalfojzq7i.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation
• Key: $DASHSCOPE_API_KEY
• Model: wan2.7-image-pro
• Why PAYG: Token Plan hits Throttling.AllocationQuota frequently.

THE 6 IRON RULES OF GEMINI IMAGE EDITING

These are field-tested from production pipelines. Violate any one and the edit fails.

Rule 1: Image First, Text Second (Parts Ordering)

In the API payload, always put the image part BEFORE the text prompt. Flipping the order causes the model to treat text as primary request and the image as a loose style reference → identity lost.

# ✅ CORRECT
parts = [
    {"inline_data": {"mime_type": "image/jpeg", "data": img_b64}},  # image FIRST
    {"text": prompt}                                                  # text SECOND
]

# ❌ WRONG — text before image
parts = [
    {"text": prompt},
    {"inline_data": {"mime_type": "image/jpeg", "data": img_b64}}
]

Rule 2: MIME Type Must Match Actual Bytes

If you label a JPEG as image/png, the decode step can silently drop the image. Always detect MIME from file header, not extension.

# ✅ Correct
mime = "image/png" if path.endswith(".png") else "image/jpeg"
# Even better: use python-magic or check first bytes

Rule 3: Image Size Sweet Spot (1024–1568px longest side)

Images outside this range cause silent failures:

• Too large (e.g., 4K): API downscales, losing fine details → edit ignores reference
• Too small (≤128px): Model behaves as if no image was attached

Fix: Pre-resize before sending.

from PIL import Image
img = Image.open(path).convert("RGB")  # Convert strips alpha channel!
longest = max(img.size)
if longest > 1568:
    ratio = 1568 / longest
    img = img.resize((int(img.size[0]*ratio), int(img.size[1]*ratio)))

Rule 4: Strip Alpha Channels from PNGs

PNGs with alpha channels cause the model to repaint transparent regions with new backgrounds → effectively rewrites the composition. Always convert to RGB.

img = Image.open(path).convert("RGB")

Rule 5: Stateless Iteration (Never Trust Multi-Turn)

Multi-turn chat sessions are unreliable for image editing. Google's own API has documented intermittent 404s and thought_signature errors on turn 2+.

Always re-attach the latest output image as fresh input each call.

# ✅ CORRECT — stateless, each call independent
result1 = edit(original_image, "add woman on left side")
result2 = edit(result1.image_bytes, "make her dress red")
result3 = edit(result2.image_bytes, "add warm lighting")

# ❌ WRONG — chat session, loses context after turn 2
session = create_chat_session()
session.send("add woman on left side")
session.send("make her dress red")  # may lose reference to original

Rule 6: One Change Per Turn

Asking for multiple changes at once causes the model to "average" them → loss of control over each individual edit.

# ✅ CORRECT — one change at a time
Turn 1: "Add a woman standing on his left side, wearing a black dress"
Turn 2: "Now make her hand rest on his chest"
Turn 3: "Add warm rim lighting to both subjects"

# ❌ WRONG — multiple changes
"Add a woman on his left in a black dress with her hand on his chest
and add warm rim lighting and change the background to dark blue"

The Prompt Architecture

The Preservation Clause (MOST IMPORTANT)

Every edit prompt MUST explicitly state what to keep AND what to change. Without the keep-list, the model is free to redraw everything.

Using the provided image as the base, change only [WHAT TO CHANGE].
Keep [WHAT TO PRESERVE] exactly as shown in the original image.
Do not alter, regenerate, smooth, or modify those preserved elements.

Identity Preservation Prompt Pattern

Place this man at [SCENE]. Keep his face and body exactly as shown.
Same [hair description], same [jawline/face description], same person.
[Scene details]. Photorealistic. No text.

Key prompt rules:

• Always start with "Place this man/woman" or "Using the provided image as the base"
• NEVER say "Transform into" or "Change to" — triggers generation mode, not edit mode
• Always include "Keep his face and body exactly as shown"
• Describe specific features: "same short spiky hair, same jawline"
• Specify scene details AFTER identity preservation clause
• End with "Photorealistic. No text."

Semantic Mask Flag

The gemini-image.py script supports --semantic-mask for automatic preservation clause injection:

python3 /root/HERMES/scripts/gemini-image.py \
  "Add a beautiful woman in black dress standing close to him" \
  --image /path/to/syed.jpg \
  --output /path/to/output.jpg \
  --model gemini-3.1-flash-image \
  --semantic-mask "man's face, muscular physique, pose, the single glowing white light tube, dark backdrop"

This auto-prepends:

"Using the provided image, change only the elements described below. Keep man's face, muscular physique, pose, the single glowing white light tube, dark backdrop exactly as shown in the original image. Do not alter, regenerate, smooth, or modify those preserved elements in any way. Edit instruction: Add a beautiful woman in black dress standing close to him"

Google's Official Prompt Best Practices (from dev blog, 2026-08-13)

1. Be hyper-specific: The more detail, the more control. Instead of "fantasy armor," describe: "ornate elven plate armor, etched with silver leaf patterns, with a high collar and pauldrons shaped like falcon wings."
2. Provide context and intent: Explain the purpose. "Create a logo for a high-end, minimalist skincare brand" > just "Create a logo."
3. Fix character consistency drifts: If features begin to drift after iterative edits, restart a fresh call with a detailed description rather than continuing the chain.
4. Aspect ratio control: When editing, model generally preserves input aspect ratio. If it doesn't, be explicit: "Do not change the input aspect ratio." For multi-image inputs, model adopts aspect ratio of the LAST image provided.
5. Camera control language: wide-angle shot, macro shot, low-angle perspective, 85mm portrait lens, Dutch angle, shallow depth of field, bokeh.

Common Failure Modes from Official Docs

• Asking for many changes at once → model averages them, lose control. One change per turn.
• Not saying what to keep → without explicit keep-list, model redraws everything. State the keep-list every time.
• Expecting long in-image text on Flash models → NB/NB2 warp logos/paragraphs. Use NB-Pro for legible text, or add text layer in external editor.
• Not saving intermediates → if iteration 7 is worse than 4, you want 4 still on disk. Download as you go.

Federation Deployment Note (2026-08-13)

This skill is profile-local (aaa-hermes/skills/media/aaa-image-editing/). It is NOT in /root/AAA/skills/ (the shared federation directory). Other agents (OpenClaw, OpenCode) cannot discover or use it.

To promote to federation-wide:

1. Copy or symlink to /root/AAA/skills/aaa-image-editing/
2. Ensure gemini-image.py script path is absolute (/root/HERMES/scripts/gemini-image.py)
3. Future architecture: expose via arifOS MCP as a governed tool (see federated-skill-architecture skill — Skill Execution Gateway pattern)

RBAC consideration: Image editing tools that call external APIs (Gemini, Qwen) should be gated by agent identity + ACT verification at the MCP layer before exposing the tool surface. Unrestricted access = blast radius risk (F1).

Identity Preservation — Known Limits

HARD RULE: Never Alter a Human's Face (F13 directive, 2026-08-12)

User ruling: "Hang jangan ubah muka manusia." When user provides a real photo and asks to edit, the person's face, body, skin tone MUST survive 100%.

Why Identity Preservation Is Technically Hard

All current image-edit models tend to generate "idealized bodybuilder templates" when editing muscular subjects — overriding actual identity. The more muscular the input, the stronger the pull toward generic output.

Composite Workaround — What Failed (2026-08-12)

Best result achieved: Gemini 2.5 Flash Image ("nano banana") — 5/10 identity, 6/10 realism. Best stage photo feel of all models tried.

Honest Workflow for Identity-Critical Edits

1. Run ensemble: NB2 + NB-Pro + Qwen with strong identity prompts
2. Verify each with vision_analyze — flag if face differs
3. Present all to user with honest realism ratings
4. Let user pick — or acknowledge "ini semua edit, bukan you sebenar"

Post-Generation Validation Checklist

Before delivering ANY edited image to user:

• Face check: Does the subject's face match the original? (use vision_analyze)
• Body check: Is the physique preserved? (not idealized/generic)
• Prop count: Are all original props present and correct count? (e.g., 1 light tube, not 2)
• No extra objects: Did the model hallucinate additional elements?
• No skin smoothing: Is skin texture preserved vs over-smoothed?
• No text/watermarks: Did "No text" instruction work?
• Aspect ratio: Does output match input aspect ratio?
• Resolution: Is output at expected resolution?

Ensemble Editing (best results for identity-critical work)

When identity preservation matters, run multiple models in parallel:

1. Nano Banana 2 (gemini-3.1-flash-image) — best all-rounder
2. Nano Banana Pro (gemini-3-pro-image) — highest fidelity
3. Nano Banana legacy (gemini-2.5-flash-image) — proven stage photo feel

Dispatch each as a separate terminal(background=true, notify_on_complete=true), wait for all, then verify with vision_analyze and present all to user.

Script Usage

# Basic edit
python3 /root/HERMES/scripts/gemini-image.py "Add woman on left" \
  --image /path/to/ref.jpg --output /path/to/out.jpg

# With semantic mask (recommended for identity preservation)
python3 /root/HERMES/scripts/gemini-image.py "Add woman on left" \
  --image /path/to/ref.jpg --output /path/to/out.jpg \
  --semantic-mask "man's face, physique, pose, light tube"

# Choose model
python3 /root/HERMES/scripts/gemini-image.py "prompt" \
  --model gemini-3.1-flash-image --image ref.jpg --output out.jpg

Script features (v2.0):

• Exponential backoff retry (3 attempts, 5s/10s/20s)
• Specific HTTP error handling (429 → retry, 400/403 → fail, 5xx → retry)
• Network error retry with backoff
• Semantic mask flag for automatic preservation clause
• Structured error output for programmatic handling

Known Failure Modes & Triage Order

When an edit goes wrong, check in this fixed order:

1. responseModalities includes IMAGE? (80% of "only text returned" bugs)
2. Parts ordered image-then-text? (wrong order → model ignores reference)
3. MIME type matches actual bytes? (wrong MIME → silent drop)
4. Image size 1024–1568px longest side? (too big/small → silent failure)
5. Prompt names what to preserve AND what to change? (vague → redrawing)
6. Stateless calls (not multi-turn chat)? (chat sessions lose context after turn 2)
7. Alpha channel stripped? (PNG alpha → model repaints transparent regions)

Endpoint Troubleshooting

Open-Source Alternatives (not yet deployed)

Session Reference

• references/mrkl-2026-identity-preservation-session.md — detailed MR KL 2026 bodybuilder case (5 approaches, model comparison, "Hang jangan ubah muka manusia")
• references/image-edit-models.md — open-source model landscape
• references/image-edit-deep-research-2026-08-13.md — compiled research: semantic inpainting, identity-preservation prompt patterns, over-smoothing root cause (AAAI 2026), client-side compositing (arXiv:2608.02841), latent-space mask engineering, and Nano Banana model lineage

Member Skills

• minimax-image-gen — generation only (image-01 via MCP :18100)
• token-plan-image — generation + basic editing (Qwen)
• This skill — editing with identity preservation + ensemble routing