Amazon Agent Iris is an MCP server that turns image generation and Amazon listing compliance into one motion. It exposes Google Gemini and OpenAI image models as MCP tools, wraps them in the amazon-product-image skill that encodes current Seller Central rules, and hands every result back as a signed URL your assistant or pipeline can use directly.
You talk to it in plain language from the AI client you already run — Claude, ChatGPT, Cursor, or your own automation. It generates a compliant main image, builds the rest of the merchandising stack, or audits a photo you already have and tells you exactly what to fix before Amazon ever sees it.
This page covers what Iris does, the rules it enforces, what you can ask it for, which model key to bring, and how your images get published to Amazon. Iris runs in your own infrastructure — Docker-ready, like the rest of the Kuudo stack — and you connect it from the AI client you already use.
What it does
The server works in three modes, all driven by natural language:
- Generate — create a new Amazon-ready image from a prompt (main image, infographic, lifestyle, detail, fashion shot).
- Edit — modify an existing image to fix a compliance problem or change one element while preserving product identity.
- Audit — check an image against the current rule set and return a verdict with the exact fix.
Generate and audit are the same surface, so you can create an image, audit it, and remediate it without leaving the conversation.
Example prompts
You drive Iris in plain language from your AI client — no tool names, fields, or APIs to remember. Replace bracketed values like [ASIN] (Amazon Standard Identification Number), [SKU], or [brand] with your own.
Find problems across the catalog
Surface what needs attention before you decide where to spend effort.
- "Scan my US listings and show me which ones have image problems."
- "Which of my live listings have empty image slots — fewer images than Amazon allows?"
- "Find my listings that are suppressed and tell me why."
- "Show me listings that only have a single image."
- "Give me a health check on [parent ASIN] and all its variations."
Diagnose one listing
Zoom in on a specific SKU to understand its current state.
- "Pull up [SKU] and tell me what's wrong with it."
- "Review the listing for [ASIN] — title, bullets, description, and images."
- "Why isn't [SKU] showing in search? What does it need to come back online?"
- "How many images does [ASIN] have, and what's missing?"
Fix listing copy
Clean up or rewrite text, grounded in the product's real attributes.
- "Rewrite the bullet points for [SKU] — it only has one and it's weak."
- "The description for [SKU] has copy-pasted text from another product. Clean it up."
- "Improve the bullets for [ASIN] using only what's true from the listing — don't invent features."
- "Make the title for [SKU] clearer and keep the brand out of the body copy."
Generate product imagery
Create new images from your real product. Lead with the scene you want.
Lifestyle / in-use shots
- "Create a lifestyle photo of [product] styled on a cream sofa in a bright, neutral living room."
- "Show a person using [product] in a warm, natural-light kitchen scene."
- "Make a cozy bedroom scene with [product] as the focal point."
Hero / product shots
- "Generate a clean studio shot of [product] on a pure white background."
- "Zoom in on the [product] so it fills more of the frame and reads as the hero image."
Infographics (added text is allowed on these auxiliary images)
- "Build a size and dimension graphic for [SKU] using the real measurements from the listing."
- "Create a feature-callout image for [product] highlighting its material, stitching, and zipper."
- "Make a care-instructions card for [product] — machine washable, etc."
- "Create a 'set of 2, covers only — no insert' graphic so buyers know what they're getting."
- "Make a color-range image showing all the available colors for this variation family."
Edit and iterate on an image
Refine an image you've already generated, in plain language.
- "Zoom in slightly on the pillow in this image."
- "Remove the books in the background — keep everything else the same."
- "Same scene, but brighter and with more natural light."
- "Make the product larger and more centered."
- "Try this again on a grey sofa instead of cream."
Check compliance before publishing
Validate against Amazon's image rules before anything goes live.
- "Check whether this image meets Amazon's compliance requirements."
- "Is text allowed on this image for the slot it's going into?"
- "Validate the file format, resolution, and color space on this image."
- "Run the policy check on all the images I've generated so far."
Publish to the listing
Write approved changes directly to the live listing.
- "Add this image to [SKU] as the first alternate image."
- "Put the size graphic into the next open slot on [SKU]."
- "Patch [SKU] with this image."
- "Apply the rewritten bullets and description to [SKU]."
Confirm it actually went live
Verify the change was accepted and the image was ingested by Amazon.
- "Check whether the new image on [SKU] ingested cleanly."
- "Did my last change to [SKU] go through, or are there any errors?"
- "Re-check [SKU] and confirm the gallery now shows the images I added."
Reuse imagery within a variation family
Fill gaps by borrowing the right images from sibling SKUs — safely.
- "This color is missing alternate images. Which images from its sibling colors can I reuse without misrepresenting it?"
- "Show me the best-stocked sibling of [SKU] and which of its images are color-neutral enough to copy."
- "Fill the empty slots on [SKU] with the generic infographics from the family, but not the color-specific shots."
Work at scale
Move from one listing to many.
- "Make a list of every listing missing a main image so I can prioritize them."
- "Which listings would benefit most from a lifestyle image? Rank them."
- "Walk me through fixing the thinnest listings one at a time."
Most real sessions chain these together. A typical one runs: "Scan my listings for image gaps" → "Let's start with [SKU]" → "Create a lifestyle photo on a cream sofa" → "Zoom in slightly" → "Check it for compliance" → "Add it to the listing" → "Confirm it ingested." Treat it as a conversation, not a set of one-off commands.
The audit verdict
When you ask for an audit, the skill returns a structured verdict rather than a vague opinion:
Status: Compliant | Needs changes | Reject
Scope: [main image / alternate / fashion / multipack / ...]
Blocking issues:
- [issue and the rule category it violates]
Non-blocking suggestions:
- [quality or conversion improvement]
Fix:
- [the exact edit instruction or replacement prompt]
References checked:
- [which rule references were applied]The verdict is graded by rule category, so a near-white background that reads ~254 instead of 255 comes back as a specific, fixable note — not a silent pass that gets your listing suppressed later.
Compliance rules it enforces
The amazon-product-image skill carries a distilled rule set from Amazon Seller Central policy. These are the rules applied during generation and checked during audit.
Main image — hard requirements
| Rule | Spec |
|---|---|
| Background | Uniform pure white, RGB 255, 255, 255 |
| Product fill | ~85% of the frame, full product visible |
| Single view | One unit, one main view (unless a multipack or assortment) |
| Props | Product only — no accessories that aren't included |
| Text & marks | No added text, logos, borders, watermarks, or badges |
| Apparel model rule | Adult apparel on-model and standing; kids, accessories, and multipacks flat (off-model); no mannequins or hangers |
| Footwear | Single shoe, left foot, 45° angle |
Technical file requirements
| Spec | Rule |
|---|---|
| Formats | JPEG (preferred), TIFF, PNG, non-animated GIF |
| Longest side | 500–10,000 px; 1,000 px+ enables zoom; 1,600–2,000 px+ preferred |
| Color | RGB preferred; CMYK may shift tonally; grayscale only for genuinely gray/silver products |
| File naming | ASIN.jpg or ASIN.VARIANT.jpg (periods as separators, no spaces or dashes) |
| Image count | Up to 9 (1 main + 8 additional); ~7 gallery thumbnails shown by default |
All-image content rules
These apply to every image in the stack, not just the main:
- No reviews, stars, ratings, prices, deals, coupons, or free-shipping claims.
- No seller info, email, copyright marks, or watermarks.
- No Amazon, Prime, Alexa, "Choice," or "Best Seller" branding or lookalikes.
- No promotional, warranty, certification, or unsubstantiated safety/health/regulatory claims.
- Every image must match the product title, ASIN, variant, color, quantity, and scale.
Special cases
| Case | Rule |
|---|---|
| Multipacks | Show the total quantity delivered; the title must state the count |
| Variety packs | Show representative items plus the total count |
| Used / collectible offer photos | Optional, separate from detail images; non-white backgrounds accepted |
Suppression issues and fixes
The skill maps the common suppression and rejection reasons to a concrete fix:
| Issue | Fix |
|---|---|
| Non-white background | Use pure white, or normalize the background field to 255 downstream |
| Text, logo, or graphics | Remove all non-product overlays |
| Cropped product | Reframe so the full product is visible |
| Additional items / props | Show the product only |
| Mannequin or hanger visible | Flat-lay, or an invisible-mannequin edit that doesn't crop the product |
| Model not standing | Use a standing model (wheelchair exception allowed) |
| Multiple views in one frame | One main view per image |
| Blurry, pixelated, or too small | Replace with a sharp image ≥500 px on the longest side |
| Unsupported / corrupted file | Re-export as JPEG/PNG/TIFF, flattened, verified locally |
| Error 100239 | Image and title don't match — correct either the title or the image and resubmit; if they already match, escalate to support with the SKU, item_name, and image URL |
Fashion, apparel, and footwear
- Adult apparel on-model and standing; kids, babies, accessories, and multipacks off-model (flat laydown).
- Framing by garment: full-length for dresses and suits, top-body for shirts, waist-down for pants and skirts.
- Footwear main image: single shoe, left foot, 45°.
- Off-model laydowns: white surface, steamed, loose threads removed, square framing.
- A 13-point fashion validation checklist covers parent/child coverage, naming (
ASIN.MAIN.jpg,ASIN.PT01.jpg,ASIN.FL01.jpg), the image set, and mobile readability.
The image stack
Most listings stop at the main image. The skill helps you build the full stack that actually converts:
| Slot | Type | Purpose |
|---|---|---|
| 1 | Main | Product on pure white; drives the search click |
| 2 | Feature | Close-up of the key differentiator |
| 3 | Infographic | Labels, dimensions, materials, contents, compatibility |
| 4 | Lifestyle | Product in real use; environment and models allowed |
| 5–7 | Angles / details | Front, side, back, interior, hardware, texture |
| 8 | Instructional | Assembly, fit, usage, or truthful before/after |
Providers and models
One server, two best-in-class image engines. The provider is chosen per session from the API key on the request — no lock-in, and the compliance rules apply identically to both.
- A Google key (
AIza…) routes to Google Gemini. Default model isgemini-3.1-flash-image("Nano Banana"), withgemini-3-pro-imageandgemini-2.5-flash-imagealso available. Resolutions0.5K,1K,2K,4Kand the full aspect-ratio set (1:1through21:9). - An OpenAI key (
sk-…) routes to OpenAIgpt-image-2via the Responses API, withsize,quality, andbackgroundcontrols.
We recommend Gemini Nano Banana for speed and cost; switch any time by changing the key.
MCP tools
The server exposes a small, clean tool surface. The two generation tools are the ones you'll use most.
| Tool | What it does | Key parameters |
|---|---|---|
start_here | Built-in workflow guide for the LLM | none |
generate_image | Generate or edit with Google Gemini | prompt, n (1–14), input_images, operation, aspect_ratio, resolution, model, interaction_id, use_grounding |
generate_openai_image | Generate with OpenAI gpt-image-2 | prompt, n (1–10), input_images, size, quality, background, output_format, previous_response_id |
create_upload_url | Mint a short-lived signed upload URL for your own image bytes (up to 40 MB) | none |
server_status | Diagnostics: auth, active providers, models, storage, health | none |
read_resource | Read a resource by URI, e.g. skill://amazon-product-image/SKILL.md | uri |
Every generated asset comes back as a signed download URL (plus a thumbnail and expiry) and is hosted for you, so it drops straight into a PIM, DAM, or ad campaign — or onto an Amazon listing, which fetches that URL directly. See Built-in media hosting below for why that matters.
Chained edits and brand-mark fidelity
To iterate without re-uploading the source image, pass the prior interaction back in:
- Gemini: reuse
interaction_idfrom a previousgenerate_imageresult (valid ~55 days on paid accounts, 1 day on free). - OpenAI: reuse
previous_response_idfrom a previousgenerate_openai_imageresult.
Brand-mark fidelity is a first-class rule on every edit. Logos, labels, and printed text are reproduced exactly — when you recolor a material, only that material changes; the wording, typography, and logo artwork stay identical to the source. A re-lettered or garbled label is treated as a compliance failure.
Built-in media hosting: Amazon pulls, it doesn't receive
Amazon's listing system is pull-based, not push-based. You never upload image bytes to Amazon. You hand it a URL, and Amazon's content pipeline runs its own GET against that URL, fetches the asset, and copies it into its CDN. The consequence is strict: an image exists to Amazon only if Amazon can reach it over the public internet, unauthenticated, at the moment it fetches.
That is why Iris hosts your media for you. A freshly generated image otherwise lives nowhere addressable — it has no point of egress, so there is literally nothing for Amazon to pull. Iris gives every generated (or uploaded) asset a public, fetchable URL the instant it is created, which is exactly the contract Amazon's pull model expects.
Why this matters more than it looks:
- It speaks Amazon's protocol natively. Amazon expects an unauthenticated,
GET-able asset; the host serves precisely that, so the integration meets the requirement instead of approximating it. - It removes the most common failure point. Without an integrated host you bolt on separate hosting — buckets, credentials, public-read policies, URL signing — each a chance to misconfigure. The classic listing-image failure is exactly this: the asset isn't reachable, Amazon's fetch fails, and the image silently never appears.
- It makes "generate and publish" one continuous motion. Because the asset is born already addressable, the handoff from "image exists" to "Amazon can fetch it" is instant. There is no manual upload step in the middle.
Bottom line: an image with no public point of egress is, to Amazon, an image that doesn't exist. The built-in media host is the reachable front door that lets the whole pipeline meet Amazon's pull model natively, rather than relying on fragile, hand-rolled hosting.
Limits and honest framing
- Amazon makes the final call. The skill materially de-risks and accelerates compliance, but it does not guarantee acceptance — Amazon does.
- The ~254 vs 255 white-background caveat. Current image models render a non-uniform near-white background around
254, not exact255, even with a perfect prompt. This is a model rendering limit, not a compression issue, and switching to PNG/TIFF doesn't fix it. Reaching exact-255 compliance needs a deterministic downstream normalization pass that clamps the background field to 255. The audit flags when that step is needed and tells you to sample the corners rather than judge by eye. - One provider per session. A request uses Gemini or OpenAI based on its key — not both in the same call.
- Synthetic images must be honest. AI-generated product images are acceptable only when they realistically represent the actual product and never hide defects, change identity, color, scale, or contents, or add prohibited text or claims.
Related
- Amazon Agent Iris feature overview — the product surface at a higher level.
- Amazon Selling Partner MCP — publish generated images straight onto listings and verify ingestion.
- Amazon Ads MCP — pull live ad performance to seed creative.
- MCP client configuration — connect Claude, ChatGPT, Cursor, and other clients.