Image Placeholder System

What It Does

During article generation, ILLIXIS automatically inserts strategic [IMAGE: description] markers throughout your content. These markers convert to interactive placeholder components that let you:

• Search free stock photos (Unsplash)
• Generate AI images
• Skip images you don't need
• Replace placeholders with actual images in one click

Why this matters: You only pay for images you actually use. Placeholders show where images would improve readability, but you decide whether to add them.

How It Works

1. Automatic Placement During Generation

When you generate content from any brief type (Keyword, Custom, Trend, Calendar, Link Magnet), the platform:

1. Analyzes your article structure (headers, word count, content flow)
2. Inserts 1-4 strategically placed markers based on article length:

• Under 500 words: 0-1 image
• 500-1000 words: 1-2 images
• 1000-2000 words: 2-3 images
• Over 2000 words: 3-4 images

3. Converts markers to placeholder components after generation

Placement rules:

• First placeholder appears after introduction (~300-400 words)
• Additional placeholders every 400-500 words
• Placed after first paragraph under section headers (never immediately after H2/H3)
• Avoids sections that already have charts or existing images

2. Interactive Placeholder Components

Each placeholder displays:

• Suggested image description (AI-generated, contextually relevant)
• Two action buttons:
• Stock Photos - Opens Unsplash search pre-filled with description
• AI Generate - Creates custom image via AI image generation
• Skip button (X) - Removes placeholder without adding image

Example placeholder:

```
┌────────────────────────────────────────────────────┐
│ 📷 Suggested Image │
│ │
│ "Woman in flowing swimwear on tropical beach at │
│ sunset, lifestyle photography style" │
│ │
│ [🔍 Stock Photos] [✨ AI Generate] [✕ Skip] │
└────────────────────────────────────────────────────┘
```

3. Resolving Placeholders

Stock Photo Search:

1. Click Stock Photos button
2. Unsplash modal opens with pre-filled search query
3. Browse results, click to insert
4. Placeholder automatically replaced with selected image

AI Image Generation:

1. Click AI Generate button
2. Image generation starts (20-30 second wait)
3. Progress indicator shows generation status
4. Once complete, placeholder replaced with AI image
5. Edit alt text or regenerate if needed

Bulk Generation:

• "Generate All Images" button in content editor
• Queues AI generation for ALL unresolved placeholders
• Track progress via notification bell

Skip Image:

• Click X button on placeholder
• Placeholder removed from content
• No cost, no action required

Where Placeholders Are Used

Content Generation (Automatic)

• Keyword Brief → Article
• Custom Brief → Article
• Trend Brief → Article
• Calendar Brief → Article
• Link Magnet Brief → Research article

Trigger: Placeholder insertion runs automatically during Phase 2 content generation.

Multilingual Siblings (Automatic)

When generating bilingual content (e.g., English → Spanish):

• Placeholders from original article copy to translated sibling
• Preserves same relative positions (after equivalent H2 sections)
• Descriptions remain in original language (works for image search and generation)

Why: Maintains visual consistency across language variants.

Content Extension (Automatic)

When extending existing articles with new sections:

• New placeholders inserted in extended sections only
• Original content placeholders unchanged

Image Style Control

Brand Settings → Image Style Description

Control what appears in ALL AI-generated images (placeholders, banners, social graphics):

Settings > Brand > Image Style

Example configuration:
```
Subjects: Women 30-50, diverse body types, Latin American aesthetic
Scenes: Beach lifestyle, tropical destinations, resort settings
Diversity: Inclusive representation of age and ethnicity
Style: Natural lighting, authentic moments, lifestyle photography
```

Applied automatically to:

• Image placeholder descriptions
• Hero image prompts (briefs)
• Banner ad backgrounds
• Social graphics
• Quote graphics

Target Audience Integration:

• target_audience field (Settings > Brand > Target Audience) also influences image diversity
• Ensures people shown in images match your customer demographics
• Fully tenant-agnostic — each account controls their own visual identity

Publishing with Unresolved Placeholders

Pre-publish validation:

• System checks for unresolved placeholders before CMS push
• Warning modal if placeholders remain:
• "Content has 2 unresolved image placeholders"
• Options: Cancel, Force Publish (strips placeholders)

Force publish behavior:

• Strips all placeholder HTML components
• Publishes clean content without placeholders
• No image generation triggered

Common Workflows

Workflow 1: Stock Photos Only (Free)

1. Generate content → 3 placeholders inserted
2. Click Stock Photos on each placeholder
3. Select images from Unsplash
4. Publish content

Workflow 2: Mixed Approach

1. Generate content → 4 placeholders inserted
2. Use Stock Photos for 2 generic scenes (free)
3. Use AI Generate for 1 brand-specific image
4. Skip 1 placeholder (not needed)
5. Publish content

Workflow 3: Bulk AI Generation

1. Generate content → 3 placeholders inserted
2. Click Generate All Images button
3. Wait 60-90 seconds for batch processing
4. Review generated images, regenerate if needed
5. Publish content

Workflow 4: Skip All (Text-Only Article)

1. Generate content → 2 placeholders inserted
2. Click X to dismiss both placeholders
3. Publish text-only content

Troubleshooting

Placeholder Not Converting to HTML

Symptom: [IMAGE: ...] marker remains as plain text

Causes:

• Post-processing service failed
• Content saved before placeholder conversion
• Manual edit introduced malformed marker

Fix:

• Regenerate content
• Ensure marker format is exact: [IMAGE: description] (no line breaks, HTML tags inside)

Bulk Generation Stalls

Symptom: "Generate All Images" starts but doesn't complete

Causes:

• Background task overload
• Image generation rate limiting
• Network timeout

Fix:

• Check notification bell for error messages
• Wait 60 seconds, retry failed images individually
• Contact support if persists

Stock Photo Search Returns No Results

Symptom: Unsplash modal shows "No results found"

Causes:

• Description too specific (e.g., "Colombian swimwear brand watercolor illustration")
• Special characters in search query

Fix:

• Click Edit Search in modal
• Simplify query (e.g., "swimwear beach lifestyle")
• Try alternative terms

Placeholder Descriptions Don't Match Brand Style

Symptom: Generic descriptions like "Woman on beach" instead of brand-specific details

Causes:

• Image style description field empty in Settings > Brand

Fix:

1. Go to Settings > Brand > Image Style
2. Add detailed description of subjects, diversity, scenes
3. Regenerate content (existing content won't update)

Cannot Publish — "Unresolved Placeholders" Warning

Symptom: Publish button blocked, modal shows placeholder count

Causes:

• Intentional validation — ensures you don't publish articles with placeholder components

Options:

1. Cancel → Resolve placeholders (stock photos, AI, or skip)
2. Force Publish → Strips placeholders, publishes clean content

Related Features

• Inline Image Library - Store, manage, and reuse inline images across content
• Hero Image Generation - AI-generated featured images for briefs
• Banner Ad Generation - Brand-aware display ads with AI backgrounds
• Social Graphics - Quote cards and social visuals with consistent branding
• Multilingual Content - Placeholders copy to translated siblings automatically

Best Practices

1. Set image style guidance first (Settings > Brand > Image Style) before generating content
2. Use stock photos for generic scenes (beaches, offices, products) — free and high quality
3. Use AI generation for brand-specific needs (unique angles, custom compositions)
4. Review descriptions before generating — edit prompt if description doesn't match vision
5. Skip placeholders liberally — not every article needs images
6. Bulk generate at end — review all placeholders, then queue all AI generations at once
7. Test with one image first — verify style matches brand before bulk generation

What's Next

Planned improvements:

• Smart image reuse - Suggest existing inline images that match placeholder description
• Custom image upload - Replace placeholder with your own uploaded image
• Batch editing - Edit all placeholder descriptions at once before generation
• Style presets - Save/load image style templates per content category