Product Tools

Tools for managing product references and generating marketing images.

Overview

The product system enables consistent product representation:

Fetch from URL, store in R2, generate unlimited consistent product scenes

---

create_product_reference

Save a product image from a URL for marketing generation.

Parameters

Parameter	Type	Required	Description
product_name	string	Yes	Unique name (1-100 chars)
product_url	string	Yes	Direct URL to product image
product_description	string	No	Product details
tags	string	No	Comma-separated tags

Example

{
  "tool": "create_product_reference",
  "params": {
    "product_name": "Premium Water Bottle",
    "product_url": "https://example.com/products/water-bottle.jpg",
    "product_description": "Stainless steel insulated bottle, matte black finish with rose gold accents, 24oz capacity",
    "tags": "drinkware,lifestyle,fitness"
  }
}

Response

Created product reference "Premium Water Bottle"

ID: 10
- Stored in R2
- Dimensions: 1200x1200
- Size: 245 KB
- Format: JPEG
- Tags: drinkware, lifestyle, fitness

Use with:
generate_with_product({
  product_name: "Premium Water Bottle",
  scene_prompt: "..."
})

Image Requirements

Ideal product photos:

• Clean white or transparent background
• High resolution (1000px+ recommended)
• Product centered and well-lit
• No watermarks or text overlays

// Good
Clean product shot on white background

// Bad
Product in cluttered scene with text overlay

---

list_product_references

Browse saved product references.

Parameters

Parameter	Type	Required	Description
search	string	No	Search name, description, tags
page	number	No	Page number (default: 1)
page_size	number	No	Results per page (default: 20, max: 100)

Example

{
  "tool": "list_product_references",
  "params": {
    "search": "bottle",
    "page_size": 10
  }
}

Response

Product References (3 matching "bottle"):

1. **Premium Water Bottle** (ID: 10)
   Used: 32 times | Tags: drinkware, lifestyle
   "Stainless steel insulated bottle..."

2. **Glass Spray Bottle** (ID: 15)
   Used: 8 times | Tags: beauty, skincare
   "Amber glass bottle with gold mister..."

3. **Kids Water Bottle** (ID: 18)
   Used: 5 times | Tags: kids, drinkware
   "Colorful plastic bottle with straw..."

Page 1 of 1

---

get_product_reference

Get full details of a specific product.

Parameters

Parameter	Type	Required	Description
id	number	Either	Product ID
product_name	string	Either	Product name

Example

{
  "tool": "get_product_reference",
  "params": {
    "product_name": "Premium Water Bottle"
  }
}

Response

Product: Premium Water Bottle (ID: 10)

**Details**
- Description: Stainless steel insulated bottle, matte black finish with rose gold accents, 24oz capacity
- Tags: drinkware, lifestyle, fitness

**Image**
- URL: https://pub-xxx.r2.dev/tenant/2024-01-10/product-abc.jpg
- Thumbnail: https://pub-xxx.r2.dev/tenant/2024-01-10/product-abc-thumb.jpg
- Dimensions: 1200x1200
- Size: 245 KB
- Format: JPEG

**Usage Stats**
- Times Used: 32
- Last Used: 2024-01-15 10:30
- Created: 2024-01-10

**Source**
- Original URL: https://example.com/products/water-bottle.jpg

---

update_product_reference

Update a saved product's name, description or tags. It does not change the product image; to replace the image, use the REST API.

Parameters

Parameter	Type	Required	Description
id	number	Either	Product ID to update
product_name	string	Either	Product name to update
new_product_name	string	No	New name (1–100 chars)
product_description	string | null	No	New description (max 500 chars); null clears it
tags	string | null	No	New comma-separated tags (max 200 chars); null clears them

Example

{
  "tool": "update_product_reference",
  "params": {
    "product_name": "Premium Water Bottle",
    "product_description": "Stainless steel insulated bottle, matte black, 24oz",
    "tags": "drinkware, fitness"
  }
}

Response

✅ Product updated: Premium Water Bottle (ID: 10)
  Description: Stainless steel insulated bottle, matte black, 24oz
  Tags: drinkware, fitness

---

delete_product_reference

Remove a product reference from your library.

Parameters

Parameter	Type	Required	Description
id	number	Either	Product ID to delete
product_name	string	Either	Product name to delete

Example

{
  "tool": "delete_product_reference",
  "params": {
    "product_name": "Old Test Product"
  }
}

Response

Deleted product reference "Old Test Product"

- R2 storage freed: 245 KB
- Generated images are not affected
- Product reference no longer available for new generations

---

generate_with_product

Generate marketing images featuring a saved product.

Parameters

Parameter	Type	Required	Description
product_id	number	Either	Product ID to use
product_name	string	Either	Product name to use
scene_prompt	string	Yes	Scene/setting description
additional_details	string	No	Extra styling details
aspect_ratio	string	No	Image aspect ratio
negative_prompt	string	No	What to avoid
number_of_images	number	No	Number to generate (1-4)

How It Works

The tool builds a specialized prompt:

"Using the provided reference image showing [product],
generate [scene_prompt]. Maintain the exact design,
colors, materials, textures, and proportions of the
product. [additional_details]"

Example: Lifestyle Shot

{
  "tool": "generate_with_product",
  "params": {
    "product_name": "Premium Water Bottle",
    "scene_prompt": "on a rustic wooden table by a sunny window, with fresh flowers and morning light",
    "additional_details": "warm atmosphere, lifestyle photography style",
    "aspect_ratio": "landscape"
  }
}

Response

Generated marketing image:

**Image #550**
- URL: https://pub-xxx.r2.dev/tenant/2024-01-15/product-gen-xyz.png
- Thumbnail: https://pub-xxx.r2.dev/.../product-gen-xyz-thumb.jpg
- Dimensions: 1024x768
- Product: Premium Water Bottle (ID: 10)

Product usage updated: 33 total uses

Scene Ideas

Category	Example Scenes
Lifestyle	"on a yoga mat in a bright studio"
Outdoor	"at a beach picnic with ocean backdrop"
Studio	"on white background with dramatic lighting"
Flat Lay	"arranged with fitness accessories from above"
In Use	"held by a hiker on a mountain trail"

---

Marketing Workflows

Campaign Generation

Generate multiple scenes for a campaign:

// Scene 1: Studio shot
{
  "tool": "generate_with_product",
  "params": {
    "product_name": "Premium Water Bottle",
    "scene_prompt": "professional studio shot on white background",
    "aspect_ratio": "square"
  }
}

// Scene 2: Lifestyle
{
  "tool": "generate_with_product",
  "params": {
    "product_name": "Premium Water Bottle",
    "scene_prompt": "on a gym bench with workout equipment",
    "aspect_ratio": "square"
  }
}

// Scene 3: Outdoor
{
  "tool": "generate_with_product",
  "params": {
    "product_name": "Premium Water Bottle",
    "scene_prompt": "being used by a hiker on a mountain trail",
    "aspect_ratio": "landscape"
  }
}

With Style Presets

Combine products with style presets for brand consistency:

{
  "tool": "generate_with_product",
  "params": {
    "product_name": "Premium Water Bottle",
    "scene_prompt": "minimalist product shot",
    "style_preset_name": "Brand Product Photography"
  }
}

---

Best Practices

Product Image Quality

Ideal:

• Clean, white or transparent background
• High resolution (1000px+)
• Product centered
• Good lighting
• No watermarks

Avoid:

• Cluttered backgrounds
• Low resolution
• Watermarks or text
• Heavy filters

Scene Description Tips

1. Be specific about setting and lighting
2. Include context for product use
3. Mention style preferences
4. Consider audience for marketing

// Good
"on a minimalist desk setup with a laptop and
plant, soft natural lighting from a window"

// Too vague
"on a table"

Organizing Products

Use consistent tagging:

Tag Type	Examples
Category	drinkware, electronics, apparel
Use Case	fitness, office, outdoor
Campaign	summer-2024, holiday-sale
Status	active, archived, seasonal

---

Use Cases

E-Commerce

Generate for:

• Product listing pages
• Category banners
• Variant displays
• Size comparisons

Social Media

Create content for:

• Instagram posts (square)
• Pinterest pins (portrait)
• Facebook ads (various)
• Stories (9:16)

Print Materials

Generate for:

• Catalogs
• Brochures
• Packaging
• Point-of-sale displays

---

Troubleshooting

Product Looks Different

Causes:

• Original image quality too low
• Heavy background interference
• Scene conflicts with product

Solutions:

• Use clean product photo
• Simplify scene description
• Add "maintain product exactly" to prompt

"Product Not Found"

Check:

• Exact spelling (case-sensitive)
• Product wasn't deleted
• Using correct tenant API key

Inconsistent Results

Tips:

• Use same aspect ratio consistently
• Apply style presets for brand consistency
• Keep scene descriptions similar in tone

Next Steps

• Analytics Tools →
• Style Preset Tools →
• Products Feature Guide →