# Blog Illustrations

_Last updated: 29 January 2026_

## Definitions

- **AI visibility**: How often and in what context AI assistants mention a brand.
- **Credits**: Usage units billed per action (e.g., scans, generations).

## Breadcrumbs

Citedy > AI > Features > Blog Illustrations

```json
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Citedy",
      "item": "https://www.citedy.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "AI",
      "item": "https://www.citedy.com/ai/index.md"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Features",
      "item": "https://www.citedy.com/ai/features/"
    },
    {
      "@type": "ListItem",
      "position": 4,
      "name": "Blog Illustrations",
      "item": "https://www.citedy.com/ai/features/blog-illustrations.md"
    }
  ]
}
```

> AI-Generated Illustrations for Articles with Multi-Provider Support

## Overview

Blog Illustrations automatically generates and embeds high-quality images into your blog articles. The system analyzes article content, selects optimal sections for images, generates multiple styles with consistent visual branding, and intelligently inserts them into your content—all with transparent credit-based pricing and built-in failure recovery.

## Capabilities

### Automatic Image Planning

- Smart section selection for image placement
- Optimal image density (1 per 600 words)
- Language-aware estimation (word or character-based)
- Intelligent fallback to heuristic selection

### Style Consistency

- Auto-generated visual style profile per article
- Consistent mood, palette, and composition across all images
- Style lock prevents visual inconsistency
- One provider per article for coherent results

### Multi-Provider Support

Configured provider pool with intelligent fallback:

- **Z.AI** (GLM-Image): ~$0.015/image, fastest
- **Google Gemini**: High-quality, $0.03/image
- **ByteDance**: Fast, ~1.8s generation
- **Alibaba Qwen**: Reliable, $0.03/image
- **Alibaba WAN 2.5**: Advanced, $0.03/image

### Content Integration

- Automatic markdown image injection
- Aspect ratio rotation (1:1, 16:9, alternating)
- Responsive layout (float on desktop, full-width on mobile)
- Full-text search support
- Lazy loading optimization

### Flexible Pricing

- 9 credits per image
- Pre-charge before generation
- Automatic refund on failure
- Bulk discounts available
- Per-image cost breakdown

## Technologies

- **AI Image Generation**: 5+ provider APIs
- **Planning**: Multi-pass analysis with fallback
- **Storage**: Supabase Storage with 30-day caching
- **Billing**: Credit system with pre-charge + refund
- **Architecture**: Parallel processing with configurable concurrency
- **Quality**: Automatic style profiling and consistency enforcement

## Pricing

- **Per image**: 9 credits
- **Image estimation**: 1 image per 600 words (English), 1 per 2400 chars (CJK)
- **Bulk articles**: No additional cost
- **Regeneration**: Same cost as generation
- **Archive download**: Included in article

## Image Density Guidelines

Based on SEO research:

- **Recommended**: 1 image per 200-300 words
- **Minimum**: 1 image per 350-500 words
- **Default formula**: ceil(wordCount / 600)

### Language-Specific Calculation

- **English, Spanish, French**: Word-based calculation
- **Chinese, Japanese, Korean**: Character-based calculation (2400 chars = ~600 words)

## How It Works

### Step 1: Enable Illustrations

- Check "Generate illustrations" in article creation
- System estimates image count and cost
- Shows estimated time and credit requirement
- Validates sufficient credits available

### Step 2: Content Analysis

- Analyzes transformed article content
- Identifies optimal sections for images
- Recalculates exact image count from final content
- Generates visual style profile for consistency

### Step 3: Parallel Image Generation

- Selects provider using round-robin scheduling
- Generates images in parallel (concurrency: 3-4)
- Applies consistent style lock to all prompts
- Falls back to next provider on failure
- Maintains same style across fallback attempts

### Step 4: Upload & Inject

- Uploads images to tenant-scoped storage
- Generates cache-friendly public URLs
- Injects images after relevant headings
- Preserves article without images if generation fails
- Refunds credits for failed images only

### Step 5: Preview & Publish

- Preview shows images in article layout
- Responsive design (float left/right on desktop)
- Mobile optimization with full-width display
- Proper text wrapping around images
- Consistent styling with article design

## Aspect Ratio Rotation

Images alternate between two formats:

- **Square (1:1)**: 1024×1024 or 1280×1280 - for featured concepts
- **Landscape (16:9)**: 1728×960 - for full-width sections

Pattern: 1:1 → 16:9 → 1:1 → 16:9 ...

**Short sections** use full-width 16:9 layout automatically.

## Rendering & Layout

### Desktop Behavior

- Images alternate left/right float
- Text wraps naturally around images
- Responsive width with CSS clamp
- Maintain 12-16px margins

### Mobile Behavior

- Full-width display
- Image above content section
- Clean stacking on narrow screens
- Optimized for touch

### CSS Classes

- `.citedy-illustration` - Float layout with text wrapping
- `.citedy-illustration-wide` - Full-width block layout
- `.citedy-article-content` - Article container

## Regeneration & Archiving

### Regenerate Illustrations

- Replace all images in article
- Keep previous versions in archive
- Same cost as initial generation
- Maintains same style profile
- Shows progress with visual feedback

### Archive Download

- Download all images as .zip
- Includes all historical versions
- Organized by article ID
- Accessible from export menu
- Useful for content repurposing

## Storage & Performance

### Storage Path

```
{STORAGE_BUCKET}/blog/{tenantId}/images/{articleId}/{imageId}.webp
```

### Cache Policy

- **TTL**: 30 days (2,592,000 seconds)
- **URLs**: UUID-based, immutable
- **CDN**: Cloudflare integration
- **Format**: WebP for compression

## Provider Details

### Z.AI (GLM-Image)

- **Speed**: ~3-6 seconds
- **Cost**: ~$0.015/image (lowest)
- **Recommended sizes**: 1280×1280 (1:1), 1728×960 (16:9)
- **Sizes**: 512-2048 px, multiples of 32
- **Output**: URL-based, requires download

### Gemini Image Generation

- **Speed**: 3-5 seconds
- **Cost**: $0.03/image
- **Quality**: High fidelity
- **Consistency**: Very good
- **Support**: Excellent fallback reliability

### ByteDance SeeDream

- **Speed**: ~1.8 seconds (fastest)
- **Cost**: $0.03/image
- **Quality**: High
- **Asian content**: Optimized
- **Coverage**: Good global support

### Alibaba Providers

- **Qwen Image Plus**: ~8.9 seconds, $0.03
- **WAN 2.5**: ~14 seconds, advanced features
- **Async support**: Available for WAN 2.5
- **Quality**: Enterprise-grade

## Failure Handling

### Graceful Degradation

- Planner fails → Use heuristic section selection
- Style generation fails → Apply default style profile
- Provider fails → Fallback to next provider
- Storage fails → Keep article without images
- Partial failure → Refund only failed images

### Refund Logic

- Pre-charge all credits upfront
- Refund immediately on failure per image
- Partial success = partial refund
- Zero impact on article generation

## Best Practices

1. **Consistent Style**: Each article gets one auto-style
2. **Provider Stability**: Let system handle round-robin
3. **Coverage**: Enable for all articles (no extra effort)
4. **Optimization**: System handles aspect ratio rotation
5. **Refunds**: Automatic handling—no manual intervention needed

## Billing Example

**10-minute read article (3000 words)**

- Estimated images: 5 (3000 ÷ 600)
- Cost: 45 credits (5 × 9)
- If 1 image fails: 36 credits charged, 9 refunded
- If all fail: 0 credits charged

## Related Features

- [Writer Agent](/ai/features/writer.md) - Article generation
- [Autopilot Agent](/ai/features/autopilot.md) - Bulk content automation
- [Solo Article](/ai/features/solo-article.md) - Single article with illustrations
- [Social Publishing](/ai/features/social-publishing.md) - Share illustrated content