# Image Prompting (per model)

`images_generate` picks a model for you when `model="auto"`, but the prompt you
write should still play to whichever model runs. Set `model` when the task clearly
calls for a specific one; otherwise let `auto` decide.

## Choosing a model (cheat sheet)

| Need | `model` |
|------|---------|
| First-pass concepts, ad ideation, everyday generation | `gpt-image-2.5-flare` |
| Precise edits, compositions with reference images, production creative | `gpt-image-2.5-sunburst` |
| Cheap iteration, the widest aspect ratios, image-to-image with multiple references | `nano-banana` |
| Readable text inside the image (posters, labels, infographics) or search-grounded scenes | `nano-banana-pro` |
| Product photography, material/fabric fidelity, accurate spatial depth | `seedream-4.5` |
| No strong preference | `auto` (default) |

## Per-model prompt shapes

### `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst` (OpenAI)
- Flare: first-pass concepts, ad creative ideation, fast everyday generation.
- Sunburst: precise edits and compositions from references, production creative.
- Prompt sections: objective → composition → style → brand constraints.
- Both take every aspect ratio between 1:3 and 3:1. Avoid long blocks of literal text.

### `nano-banana` (Gemini)
- Best for: high-resolution refinements, broad aspect ratios, image-to-image with multiple references.
- Prompt sections: subject → composition → style → lighting.
- Avoid competing visual instructions in the same prompt.

### `nano-banana-pro` (Gemini Pro)
- Best for: exact readable text inside the image (posters, labels, infographics) and search-grounded scenes.
- Prompt sections: exact_text → layout → hierarchy → style → aspect_ratio.
- Avoid ambiguous copy and too many independent text blocks.

### `seedream-4.5`
- Best for: product photography, material/fabric preservation, scenes requiring accurate spatial depth.
- Prompt sections: product_identity → surface_materials → lighting → camera_angle → environment.
- Avoid changing logo/text, warping packaging geometry, and busy backgrounds.

## Parameters

`images_generate` takes: `requests` (each `{prompt, id?, reference_images?}`),
`model`, `aspect_ratio`, `quality` (`"draft" | "standard" | "high"`), `n` (1-4),
`seed`, and `use_search`. `aspect_ratio` is the single spatial control and `quality`
covers the resolution/quality tier across models — pass intent through those, not
raw pixel sizes.

# Marketplace Cards Reference

Use `images_marketplace_cards_create` for the standard image set retailers expect on a listing — Amazon main image + secondary images + A+ modules, Shopify product images, Etsy product photos.

## Scopes

Pick a scope and the tool expands it to the deterministic asset set:

| Scope | Assets |
|-------|--------|
| `main` | `main_image` |
| `product_images` | `main_image`, `infographic`, `multi_angle`, `detail_shot`, `lifestyle`, `whats_in_box` |
| `aplus` | `aplus_hero_banner`, `aplus_pain_points`, `aplus_features`, `aplus_ingredients`, `aplus_efficacy`, `aplus_how_to_use` |
| `full_set` | `product_images` + selected A+ modules |

You can override the scope by passing an explicit `assets=[...]` list.

## Per-asset framing

Each asset has its own aspect ratio and prompt focus baked in:

- `main_image` — pure white background, product fills 85% of the frame, no overlays. **1:1**
- `infographic` — feature callouts with icons + short labels. **1:1**
- `multi_angle` — three-angle composite, consistent lighting. **1:1**
- `detail_shot` — extreme close-up on signature feature, shallow depth. **1:1**
- `lifestyle` — real environment of intended use. **4:5**
- `whats_in_box` — flat lay of every included item, neutral background. **1:1**
- `aplus_hero_banner` — wide hero with negative space, premium lighting. **16:9**
- `aplus_pain_points` — before/after split or icon grid. **16:9**
- `aplus_features` — three to four feature tiles. **16:9**
- `aplus_ingredients` — ingredient hero shots with sourcing notes. **16:9**
- `aplus_efficacy` — results-led visual with supporting metric. **16:9**
- `aplus_how_to_use` — numbered usage steps with hands-on shots. **16:9**

## Marketplace targeting

`marketplace="amazon" | "shopify" | "etsy" | "generic"` adds a per-target compliance hint to every prompt — e.g. Amazon enforces white background on the main image and no logos/watermarks. Use `generic` when the listing isn't tied to a specific marketplace.

## Identity preservation

Every asset prompt includes preservation clauses (logo/text exact, geometry, colorway, material, scale). Pass product references via `product.references` so the underlying image-to-image backend has them.

## Example

```python
images_marketplace_cards_create(
    product=ProductContext(
        name="Glow Vitamin C Serum",
        brand_name="Glow Lab",
        selling_points=[
            "20% L-ascorbic acid",
            "vegan",
            "results in 4 weeks",
        ],
        references=[MediaInput(file_id="file_image_gen_..._serum")],
    ),
    scope="product_images",
    marketplace="amazon",
    quality="high",
)
```

# Product Photoshoot Reference

Use `images_product_photoshoots_create` (not generic image generation) whenever the goal is on-brand product or campaign visuals. The tool wraps prompt construction, identity preservation, and variant generation so you don't have to reinvent it per call.

## When to use

- The user asks for "product photos", "product shots", "lifestyle photos", "hero banner", "campaign image", "moodboard", "ad creative pack", "carousel", or similar.
- You have a `ProductContext` (name, brand, references, selling points) — even a partial one.
- You want multiple variants from a single call.

## Modes

| Mode | What it produces | Default aspect |
|------|------------------|----------------|
| `product_shot` | Clean studio catalog shot | 1:1 |
| `lifestyle_scene` | Real-environment in-use moment | 4:5 |
| `closeup_product_with_person` | Tight crop with hands or partial face | 4:5 |
| `moodboard_pin` | Pinterest-style moodboard composition | 2:3 |
| `hero_banner` | 16:9 campaign banner with negative space | 16:9 |
| `social_carousel` | Connected slide system with shared palette | 4:5 |
| `ad_creative_pack` | Paid social variants with offer/hook areas | 1:1 |
| `virtual_model_tryout` | Model wearing or using product | 4:5 |
| `conceptual_product` | Surreal CGI styling, levitation/splash | 1:1 |
| `restyle` | Keep subject, change mood/season/styling | mode default |

## Variant strategy

`variant_strategy` controls which dimension changes between variants:

- `angles` — front, three-quarter, top-down, low angle, side, back
- `scenes` — kitchen, café, studio, desk, soft daylight, dinner table
- `hooks` — before/after, problem/solution, scroll-stop, social proof
- `palette` — warm, cool, mono, high contrast, pastel, earthy
- `props` — minimal, matched accessories, ingredient props, lifestyle, food, outdoor
- `mixed` — automatic, picks the natural strategy for the mode

## Identity preservation

The tool always inserts these clauses (unless `preserve_product_identity=False`):

- Preserve logo and printed text exactly
- Preserve packaging geometry and proportions
- Preserve colorway and material finish
- Keep product scale and silhouette accurate

If `product.brand_colors` is set, it's also added as a respect-palette constraint. Anything in `product.constraints` is appended verbatim.

## Example

```python
images_product_photoshoots_create(
    product=ProductContext(
        name="Ember Travel Mug",
        category="insulated travel mug",
        brand_name="Ember",
        brand_colors=["#0F172A", "#FFEED9"],
        selling_points=[
            "leakproof closure",
            "16-hour heat retention",
        ],
        references=[MediaInput(file_id="file_image_gen_..._mug")],
    ),
    mode="lifestyle_scene",
    prompt="Morning commute, modern apartment kitchen, warm light",
    count=4,
    variant_strategy="scenes",
    quality="high",
)
```