# Asset Generation & Management

> Generate, composite, import, and view custom images for page sections with AI-powered tools

Canonical URL: https://fa7e86e3d553:3005/tools/assets

Generate, composite, import, and view custom images for page sections. Use these tools when existing brand assets aren't available or need customization.

Use the MCP v3 routers:

- `lexsis_asset_library` action `search`
- `lexsis_asset_select` action `select`
- `lexsis_assets` actions `capabilities` and `view`
- `lexsis_asset_import` action `import`
- `lexsis_asset_upload` action `upload`
- `lexsis_drafts` action `asset_generate`

Call `lexsis_discover` for authoritative action schemas. Former operation names
remain searchable but are not top-level tools on the consolidated endpoint.

---

## Decision Tree: Reuse vs Generate

**Always follow this sequence:**

```
Need an image?
│
├─ lexsis_asset_library → search
│  ├─ Found one clear match → USE IT (free, brand-consistent)
│  ├─ User should choose → lexsis_asset_select → select
│  └─ No match → GENERATE or IMPORT
│
├─ Product image needed?
│  ├─ get_product({ product_ids: [...] }) has images → USE THOSE
│  └─ Need custom composite → lexsis_drafts → asset_generate
│
├─ External MCP generated an image?
│  └─ lexsis_asset_import → import → persists + makes searchable
│
├─ User wants to choose a local file?
│  └─ lexsis_asset_upload → upload → opens the upload panel
│
└─ Custom background/texture → lexsis_drafts → asset_generate
```

**Rule: Always search the asset library first.** Only generate when the
library has nothing suitable.

---

## Search the asset library

Search existing product shots, lifestyle images, textures, SVGs, and videos.
The query is optional: omit it to browse the complete library.

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | `string` | No | Natural-language query; omit to browse |
| `kind` | `"image"` \| `"video"` \| `"svg"` | No | Filter by asset type |
| `mode` | `"all"` \| `"filename"` \| `"alt_text"` \| `"tags"` \| `"ocr"` \| `"semantic"` \| `"similar"` | No | Search strategy; default `all` |
| `similar_to_asset_id` | UUID | For `mode:"similar"` | Source image for visual-similarity search |
| `category` | asset category | No | Filter by canonical category such as `product`, `lifestyle`, or `logos_trust` |
| `subtype` | asset subtype | No | Filter by canonical subtype such as `product-shot`, `editorial`, or `trust-icon` |
| `limit` | `number` (1-50) | No | Assets per page; default and maximum 50 |
| `cursor` | `string` | No | Cursor returned by the previous page |
| `theme_id` | `string` (UUID) | **Yes**, unless using the deprecated alias | Selected theme that owns the asset search |
| `brand_kit_id` | `string` (UUID) | No | Deprecated compatibility alias for `theme_id` |
| `workspace_id` | `string` (UUID) | No | Target workspace; required when the authenticated account has multiple workspaces |

### Returns

Paginated asset response:

```json
{
  "assets": [
    {
      "id": "uuid",
      "original_url": "https://...",
      "thumbnail_url": "https://...",
      "url": "https://...",
      "name": "serum-marble.png",
      "tags": ["lifestyle", "marble", "natural-light"],
      "kind": "image",
      "width": 1920,
      "height": 1080,
      "format": "png",
      "usage_hint": "Hero or product story"
    }
  ],
  "total": 42,
  "next_cursor": "cursor-value",
  "has_more": true,
  "request": {
    "query": "serum bottle",
    "mode": "all",
    "kind": "image",
    "limit": 50
  }
}
```

### Example

**Tool call:**
```json
{
  "name": "lexsis_asset_library",
  "arguments": {
    "action": "search",
    "args": {
      "query": "serum bottle lifestyle natural light",
      "mode": "semantic",
      "kind": "image",
      "limit": 12,
      "theme_id": "theme-uuid",
      "workspace_id": "workspace-uuid"
    }
  }
}
```

Use `filename`, `alt_text`, `tags`, or `ocr` when you need an exact field.
Use `semantic` for conceptual retrieval and `similar` when you already have a
source asset.

In an MCP Apps host, search opens a read-only result panel showing the exact
query, active filters, result count, pagination state, and previews. Search
does not ask the user to select anything, and the agent does not wait after
the result.

Asset search, similarity lookup, metadata updates, deletion, downloads, and
imports are scoped by both tenant and workspace. Automatic workspace selection
is allowed only when exactly one active workspace is available.

### When to Use

- **Before generating any new image** — check whether it already exists
- When building a page and you need a hero background or product lifestyle shot
- To find brand-approved textures, patterns, or decorative elements

---

## Select existing assets

Use `lexsis_asset_select` when the user should choose among existing library
assets. Its `select` action accepts the same query, mode, type, category,
subtype, theme, workspace, limit, and cursor arguments as asset search.

Search first when the agent needs to inspect or narrow the candidates. The
selector can also be opened directly when the desired scope is already known.

```json
{
  "name": "lexsis_asset_select",
  "arguments": {
    "action": "select",
    "args": {
      "query": "serum bottle lifestyle natural light",
      "mode": "semantic",
      "kind": "image",
      "theme_id": "theme-uuid",
      "workspace_id": "workspace-uuid"
    }
  }
}
```

The picker supports category browsing, pages of up to 50 assets, keyboard
selection, and multi-select. After **Use selected**, the agent receives the
chosen assets in selection order with each asset's name, ID, and original URL.
The agent waits only after this selector call.

---

## Generate or edit an asset

Generate a new AI-powered image when no existing brand asset matches. Returns
`{ asset_id, url }` — pass the URL to `HeroMedia`, `MediaCarousel`,
`ProductGallery`, `ProductHero`, or another island media prop.

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `prompt` | `string` | **Yes** | Image generation prompt |
| `style` | `"photography"` \| `"editorial"` \| `"abstract"` \| `"texture"` \| `"3d_render"` \| `"illustration"` \| `"flat_lay"` \| `"lifestyle"` | **Yes** | Visual style |
| `purpose` | `"hero_bg"` \| `"product_lifestyle"` \| `"texture_fill"` \| `"decorative_element"` \| `"section_bg"` \| `"card_bg"` \| `"pattern_tile"` \| `"product_composite"` | **Yes** | Where this asset will be used |
| `aspect` | `"landscape"` \| `"square"` \| `"portrait"` | No | Aspect ratio (default: landscape) |
| `quality` | `"low"` \| `"medium"` \| `"high"` | No | Quality tier (cost control, default: medium) |
| `transparent` | `boolean` | No | Transparent background (PNG, default: false) |
| `reference_images` | `string[]` (1-16 URLs) | No | Ordered source images. Supplying one or more turns the request into an edit, composite, or style-transfer operation. |
| `mask_url` | `string` (URL) | No | Optional semantic mask. Transparent or white regions identify the requested edit area. |
| `provider` | `string` | No | Registry-defined image provider ID, such as `"openai"` or `"gemini"` (default: OpenAI). |
| `model` | `string` | No | Provider model ID. Call `lexsis_assets` action `capabilities` first |
| `aspect_ratio` | `string` | No | Explicit provider-supported ratio such as `"16:9"` or `"1:1"`. |
| `image_size` | `string` | No | Provider-supported output size, such as `"1K"`, `"2K"`, or `"4K"`. |
| `output_format` | `string` | No | Provider-supported output format. |
| `brand_colors` | `string[]` | No | Brand hex colors for consistency |
| `brand_tone` | `string` | No | Brand tone for style matching |

### Returns

Generated asset object:

```json
{
  "asset_id": "uuid",
  "url": "https://cdn.lexsis.app/assets/...",
  "kind": "image",
  "width": 1536,
  "height": 1024
}
```

### Example

**Tool call:**
```json
{
  "name": "lexsis_drafts",
  "arguments": {
    "action": "asset_generate",
    "args": {
      "prompt": "Soft gradient background with subtle botanical shadows, sage green tones, editorial feel",
      "style": "editorial",
      "purpose": "hero_bg",
      "aspect": "landscape",
      "quality": "high",
      "brand_colors": ["#2D5016", "#F5F0EB"],
      "brand_tone": "editorial_cream"
    }
  }
}
```

**Response:**
```json
{
  "asset_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
  "url": "https://cdn.lexsis.app/assets/gen/f6a7b8c9-hero-bg.jpg",
  "kind": "image",
  "width": 1536,
  "height": 1024
}
```

### When to Use

- When `lexsis_asset_library` returns no suitable matches
- For custom hero backgrounds
- To generate textures, patterns, or decorative elements
- When you need a specific mood/style not in the existing library
- To edit, restyle, or composite existing assets by supplying `reference_images`

**Cost control:**
- `quality: "low"` — textures, patterns, decorative elements
- `quality: "medium"` — card images, section backgrounds
- `quality: "high"` — hero images, primary product shots
- Basic image models cost **1 credit**. `gemini-3-pro-image` costs **2 credits**.

---

## Composite or edit with `asset_generate`

Use the same tool to place products into a new scene, combine multiple products, restyle an image, or target a semantic mask.

### Example: Product on Background Composite

**Step 1: Generate background**
```json
{
  "name": "lexsis_drafts",
  "arguments": {
    "action": "asset_generate",
    "args": {
      "prompt": "Marble countertop with soft morning light, botanical shadows",
      "style": "photography",
      "purpose": "product_composite",
      "aspect": "square"
    }
  }
}
```

**Step 2: Composite product onto it**
```json
{
  "name": "lexsis_drafts",
  "arguments": {
    "action": "asset_generate",
    "args": {
      "reference_images": ["<product_image_url>", "<bg_url>"],
      "prompt": "Place the product bottle centered on the marble surface, natural shadows, studio lighting",
      "style": "photography",
      "purpose": "product_composite",
      "aspect": "square",
      "quality": "high",
      "provider": "gemini",
      "model": "gemini-3.1-flash-image"
    }
  }
}
```

**Response:**
```json
{
  "asset_id": "g7b8c9d0-e1f2-3a4b-5c6d-7e8f9a0b1c2d",
  "url": "https://cdn.lexsis.app/assets/gen/composite-product.jpg",
  "kind": "image",
  "width": 1024,
  "height": 1024,
  "provider": "gemini",
  "model": "gemini-3.1-flash-image",
  "credit_cost": 1,
  "credits_charged": 1
}
```

### Gemini Nano Banana Models

Call `lexsis_assets` action `capabilities` to see the enabled model, format,
size, and ratio combinations in your workspace.

- Nano Banana 2 Lite (Gemini 3.1 Flash Lite Image, `gemini-3.1-flash-lite-image`): fastest, cheapest Gemini image model, engineered for velocity and scale where speed and cost are the primary operational constraints; it is not optimized for multiple references or multi-turn sequential editing.
- Nano Banana 2 (Gemini 3.1 Flash Image, `gemini-3.1-flash-image`): serves as the most versatile model and generalist workhorse for all tasks; balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering, excelling at multiple reference image processing and consistency.
- Nano Banana Pro (Gemini 3 Pro Image, `gemini-3-pro-image`): costs 2 credits and targets the most complex visual tasks, offering the highest level of world knowledge, advanced localization, accurate brand consistency, and precision creative control.
- Nano Banana (Gemini 2.5 Flash Image, `gemini-2.5-flash-image`): legacy pioneer of the Nano Banana series; while it has been a reliable workhorse, we strongly recommend that customers transition to Nano Banana 2 Lite to experience enhanced quality, faster generation speeds, and lower API pricing.

Gemini-generated images include a SynthID watermark. Transparent background output depends on the selected provider and the returned image; do not treat a prompt request alone as proof of an alpha channel.

---

## List image capabilities

Call this read-only tool before selecting an unfamiliar provider or model. It
returns the enabled provider/model combinations for the workspace and validates
the settings `lexsis_drafts` action `asset_generate` can accept.

**Tool call:**
```json
{
  "name": "lexsis_assets",
  "arguments": {
    "action": "capabilities",
    "args": {}
  }
}
```

**Response:**
```json
[
  {
    "provider": "gemini",
    "model": "gemini-3.1-flash-image",
    "operations": ["edit", "generate"],
    "aspect_ratios": ["1:1", "16:9", "21:9"],
    "image_sizes": ["512px", "1K", "2K", "4K"],
    "output_formats": ["jpeg", "png"],
    "max_reference_images": 14,
    "credits": 1
  }
]
```

Use the returned values rather than guessing model, ratio, format, or
reference-image support. Image credits are attached to the exact
`provider/model` pair shown by this response; there is no generic basic or
premium operation tier. Supplying `mask_url` requires at least one
`reference_images` entry.

---

## View an asset

Resolve an `asset_id` to a viewable image content block. **Requires vision-capable model.** Use when you need to SEE the image.

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `asset_id` | `string` (UUID) | **Yes** | Asset UUID from generation, upload, or user selection |

### Returns

Image content block (base64-encoded JPEG):

```json
{
  "content": [
    {
      "type": "image",
      "data": "<base64>",
      "mimeType": "image/jpeg"
    },
    {
      "type": "text",
      "text": "{\"asset_id\": \"...\", \"url\": \"...\", ...}"
    }
  ]
}
```

### Example

**Tool call:**
```json
{
  "name": "lexsis_assets",
  "arguments": {
    "action": "view",
    "args": {
      "asset_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c"
    }
  }
}
```

### When to Use

- When you need to verify the generated image looks correct
- To let a vision model analyze the image (e.g., "does this match the brand?")
- For debugging — check if an asset_id resolves to the expected image

---

## Import an asset

Bring an image into the asset library from one of three sources:

1. **`url`** — download and import an external image. Use this when another MCP tool (Higgs Field, DALL-E, any image generator) produced an image you want on a storefront page.
2. **`data`** — import base64 bytes you already hold.
3. **`attachments`** — import one or more conversation attachments.

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `url` | `string` (URL) | One of url/data | External URL to download and import |
| `data` | `string` (base64) | One of url/data | Base64-encoded image data |
| `filename` | `string` | No | Desired filename with extension (e.g. `hero-background.png`). Derived from the URL or MIME type when omitted |
| `alt_text` | `string` | No | Alt text for accessibility and SEO |
| `tags` | `string[]` | No | Searchable user-authored tags |
| `purpose` | `string` | No | Intended use such as `hero_bg` or `trust_icon` |
| `mime_type` | `string` | When using `data` | MIME type (e.g. `image/png`, `image/webp`) |
| `attachments` | `object[]` | Alternative source | Batch conversation attachments with `attachment_id`, optional filename, alt text, tags, and purpose |
| `workspace_id` | `string` (UUID) | No | Target workspace; pass it explicitly for multi-workspace accounts |

**Validation:** Choose exactly one of `url`, `data`, or `attachments`. When
using `data`, `mime_type` is required.

> **Current limitation:** Asset import does not yet expose an idempotency key.
> After a timeout, search by the intended filename or inspect the library before
> retrying so a second request does not create a duplicate.

HEIC or HEIF provided by URL or base64 is converted to PNG when the runtime can
decode it. If conversion is unavailable, the response reports a conversion
error instead of silently importing an unreadable file.

### Returns

Imported asset object:

```json
{
  "id": "uuid",
  "asset_id": "uuid",
  "url": "https://pcx-assets.trylexsis.com/pcx/.../image.webp",
  "kind": "image",
  "width": 1536,
  "height": 1024,
  "alt_text": "Descriptive alt text",
  "srcset_webp": "...",
  "fallback_url": "...",
  "processing_status": "ready",
  "delivery_provider": "r2",
  "delivery": {}
}
```

The response can include responsive delivery variants and processing status.
Use the returned permanent URL rather than the temporary source URL.

### Example: Import from External URL

**Tool call:**
```json
{
  "name": "lexsis_asset_import",
  "arguments": {
    "action": "import",
    "args": {
      "url": "https://fal.media/files/generated/hero-gradient.png",
      "filename": "hero-gradient.png",
      "alt_text": "Neon gradient background with purple and blue tones",
      "workspace_id": "workspace-uuid"
    }
  }
}
```

### Example: Import from Base64 (another MCP returned raw data)

**Tool call:**
```json
{
  "name": "lexsis_asset_import",
  "arguments": {
    "action": "import",
    "args": {
      "data": "<base64-encoded-image>",
      "filename": "ai-generated-texture.webp",
      "mime_type": "image/webp",
      "alt_text": "Abstract organic texture",
      "workspace_id": "workspace-uuid"
    }
  }
}
```

### Conversation attachments

Import conversation attachments directly:

```json
{
  "name": "lexsis_asset_import",
  "arguments": {
    "action": "import",
    "args": {
      "workspace_id": "workspace-uuid",
      "attachments": [
        {
          "attachment_id": "attachment-uuid",
          "filename": "secure-payments.png",
          "alt_text": "Secure payment trust icon",
          "tags": ["trust", "checkout"],
          "purpose": "trust_icon"
        }
      ]
    }
  }
}
```

User-supplied filenames, alt text, tags, and purpose are marked as user
metadata and remain authoritative during asynchronous enrichment.

### When to Use

- When another MCP tool generated an image (Higgs Field, DALL-E wrapper, Midjourney, etc.)
- When you have an external image URL that may expire and need to persist it
- When importing images from design tools or external CDNs into the brand library
- To make externally-generated images searchable in `lexsis_asset_library`

### Multi-MCP Workflow

```
1. Generate image with external MCP:
   higgs_field.generate_image({ prompt: "neon gradient background" })
   → returns temporary URL

2. Import into Lexsis:
   lexsis_asset_import → import
   → returns { asset_id, url } with permanent CDN URL

3. Use in page:
   lexsis_drafts → page_update_section or page_patch
```

---

## Upload a local asset

Use `lexsis_asset_upload` when the user wants to choose an image or video from
their device. The `upload` action opens the interactive upload panel and accepts
optional `workspace_id` and `theme_id` values.

```json
{
  "name": "lexsis_asset_upload",
  "arguments": {
    "action": "upload",
    "args": {
      "workspace_id": "workspace-uuid",
      "theme_id": "theme-uuid"
    }
  }
}
```

The uploaded asset arrives in the conversation with its asset ID, name, and
permanent URL. See [Interactive Widgets](/tools/interactive-widgets).

---

## Workflow: Asset Generation

```
1. lexsis_asset_library → search
   → Check for existing assets first

2. If the user should choose among matches:
   lexsis_asset_select → select
   → Wait for the ordered selection message

3. If no match:
   lexsis_drafts → asset_generate
   → Generate image
   → Returns { asset_id, url }

4. lexsis_assets → view
   → Verify it looks correct

5. Use the URL in page HTML:
   Use the returned URL in the selected native media island's `media`,
   `images`, or `src` prop.
```

**Budget per page:**
- PDP: 1 high (hero) + 1-2 medium (lifestyle) = 2-3 assets
- Landing: 1 high (hero) + 2-3 medium (section backgrounds) = 3-4 assets
- Homepage: 1 high (hero) + 1 medium (brand story) = 2 assets
- Collection: 0-1 medium (header) — products have their own images

Always search for existing assets before generating new ones. Use
`lexsis_asset_select` only when the user should make the final choice.