banatie-service/inbox/task-placeholder-guide-rewrite.md

# Task: Rewrite Placeholder Images Guide

**Priority:** High
**Estimated time:** 1-2 hours
**Type:** Documentation rewrite

---

## Overview

Delete current `/docs/guides/placeholder-images/page.tsx` and create new guide with structure below.

**Tone:** Technical, professional, concise. No marketing fluff.
**Audience:** Developers who want practical examples they can copy-paste.

**Live examples:** Use `https://cdn.banatie.app/sys/demo/live/{scope}` for all images.

---

## SEO Metadata

Keep existing SEO config in `docs-seo.ts` for `guide-placeholder-images`:

```typescript
'guide-placeholder-images': {
  path: '/docs/guides/placeholder-images/',
  title: 'AI Placeholder Images Guide | Banatie',
  description:
    'Generate AI placeholder images for development. Replace gray boxes with contextual visuals. Sizes for avatars, thumbnails, heroes, and more.',
  keywords: [
    'placeholder images',
    'ai placeholder generator',
    'placeholder image api',
    'image placeholder dark',
    'profile placeholder image',
    'placeholder image url',
    'dummy image generator',
  ],
},
```

---

## Page Structure

```
tocItems = [
  { id: 'what-this-guide-covers', text: 'What This Guide Covers', level: 2 },
  { id: 'ai-generation-basics', text: 'AI Generation Basics', level: 2 },
  { id: 'quick-start', text: 'Quick Start', level: 2 },
  { id: 'organizing-placeholders', text: 'Organizing Placeholders', level: 2 },
  { id: 'prompt-tips', text: 'Prompt Tips', level: 2 },
  { id: 'avatar-placeholder', text: 'Avatar Placeholder', level: 2 },
  { id: 'product-image', text: 'Product Image', level: 2 },
  { id: 'hero-section', text: 'Hero Section', level: 2 },
  { id: 'og-image', text: 'OG Image', level: 2 },
  { id: 'features-block', text: 'Features Block', level: 2 },
  { id: 'file-based-workflow', text: 'File-based Workflow', level: 2 },
]
```

---

## Content

### Hero

**Title:** AI Placeholder Images

**Subtitle:** Generate contextual images for development. Copy-paste ready examples with Tailwind CSS.

---

### Section: What This Guide Covers

This guide shows how to generate placeholder images with Banatie:

- **Live URLs** — embed AI-generated images directly in HTML
- **Ready-to-use snippets** — copy into your project with Tailwind classes
- **File download** — save images locally via API

All examples use real Live URLs. Images you see on this page are generated by Banatie.

---

### Section: AI Generation Basics

Banatie generates images from text descriptions. Key concepts:

**Prompt → Image**
Describe what you need. The AI generates a matching image.

**Prompt Enhancement**
Short prompts are automatically expanded. "office" becomes a detailed description with lighting, composition, and style.

**Templates**
Control visual style with the `template` parameter:
- `photorealistic` — photo-like images
- `digital-art` — stylized illustrations
- `3d-render` — 3D graphics

**Caching**
Same prompt returns the same image. First request generates, subsequent requests serve from cache instantly.

---

### Section: Quick Start

Basic Live URL format:

```
https://cdn.banatie.app/{org}/{project}/live/{scope}?prompt={description}&aspectRatio={ratio}
```

Minimal example:

```html
<img
  src="https://cdn.banatie.app/landing/demo/live/test?prompt=mountain+landscape"
  alt="Mountain landscape"
/>
```

Parameters:

| Parameter | Required | Description |
|-----------|----------|-------------|
| `prompt` | Yes | Image description (URL-encoded) |
| `aspectRatio` | No | Ratio like `1:1`, `16:9`, `4:3` (default: `16:9`) |
| `template` | No | Style template name |

For full parameter reference, see [Live URLs documentation](/docs/live-urls/).

---

### Section: Organizing Placeholders

Use scopes to group related images:

```
/live/avatars?prompt=...    → team member photos
/live/products?prompt=...   → product catalog
/live/blog?prompt=...       → article images
/live/hero?prompt=...       → hero sections
```

Scopes are created automatically on first use. Each scope maintains its own cache.

For scope configuration and limits, see [Live URLs → Scopes](/docs/live-urls/#scopes).

---

### Section: Prompt Tips

**Be specific**

```
❌ "office"
✅ "modern minimalist office with plants and natural light"
```

**Dark mode**

Include theme context in your prompt:

```
"abstract gradient background dark theme"
"product photo on dark surface moody lighting"
"avatar silhouette dark background"
```

**Consistent style**

Use the `template` parameter for visual consistency across multiple images:

```
?prompt=...&template=photorealistic
?prompt=...&template=digital-art
```

[TIP] All examples in this guide use prompt enhancement. Your short descriptions are automatically expanded into detailed prompts.

---

### Section: Avatar Placeholder

**Aspect ratio:** `1:1`

**Use case:** User profiles, team sections, testimonials.

#### Live Example

[LIVE_PREVIEW: testimonial-card]

Create a testimonial card component with:
- Dark card background (slate-800)
- Avatar image: 64x64px, rounded-full
- Quote text
- Author name and role
- Use this exact URL: `https://cdn.banatie.app/landing/demo/live/avatars?prompt=professional+studio+headshot+confident+woman+neutral+background&aspectRatio=1:1`
- Quote: "Banatie cut our design mockup time in half. No more hunting for stock photos."
- Author: "Sarah Chen"
- Role: "Product Designer at Acme"

[/LIVE_PREVIEW]

#### Code Snippet

```html
<img
  src="https://cdn.banatie.app/{org}/{project}/live/avatars?prompt=professional+studio+headshot&aspectRatio=1:1"
  alt="User avatar"
  class="w-16 h-16 rounded-full object-cover"
/>
```

#### Team Grid Example

[LIVE_PREVIEW: team-grid]

Create a 3-column responsive grid with:
- 3 avatar cards side by side on desktop, stacked on mobile
- Each card: avatar (48x48, rounded-full), name, role
- Gap between cards
- Use these URLs:
  1. `https://cdn.banatie.app/landing/demo/live/avatars?prompt=professional+headshot+young+man+friendly+smile&aspectRatio=1:1` — "Alex Rivera", "Engineering Lead"
  2. `https://cdn.banatie.app/landing/demo/live/avatars?prompt=professional+headshot+woman+glasses+confident&aspectRatio=1:1` — "Maria Santos", "Design Director"
  3. `https://cdn.banatie.app/landing/demo/live/avatars?prompt=professional+headshot+man+beard+casual&aspectRatio=1:1` — "James Wilson", "Product Manager"

[/LIVE_PREVIEW]

---

### Section: Product Image

**Aspect ratio:** `1:1` (square) or `4:5` (portrait)

**Use case:** E-commerce catalogs, product cards, listings.

#### Live Example

[LIVE_PREVIEW: product-card]

Create a product card with:
- White/light background card with subtle shadow
- Product image: square, rounded corners
- Product name
- Price
- "Add to Cart" button (small, secondary style)
- Use URL: `https://cdn.banatie.app/landing/demo/live/products?prompt=minimalist+wireless+headphones+white+background+product+photo&aspectRatio=1:1`
- Name: "Wireless Pro Headphones"
- Price: "$299"

[/LIVE_PREVIEW]

#### Code Snippet

```html
<img
  src="https://cdn.banatie.app/{org}/{project}/live/products?prompt=product+photo+white+background&aspectRatio=1:1"
  alt="Product"
  class="w-full aspect-square object-cover rounded-lg"
/>
```

#### Product Grid Example

[LIVE_PREVIEW: product-grid]

Create a 2x2 product grid:
- 4 product cards
- Each: image (1:1), name, price
- Use these:
  1. `?prompt=modern+smart+watch+product+photo` — "Smart Watch X1", "$199"
  2. `?prompt=wireless+earbuds+case+product+photo` — "AirPods Pro", "$249"
  3. `?prompt=portable+bluetooth+speaker+product+photo` — "Portable Speaker", "$79"
  4. `?prompt=laptop+stand+aluminum+product+photo` — "Laptop Stand", "$129"

Base URL: `https://cdn.banatie.app/landing/demo/live/products` with `&aspectRatio=1:1`

[/LIVE_PREVIEW]

---

### Section: Hero Section

**Aspect ratio:** `16:9`

**Use case:** Landing page heroes, section backgrounds, feature highlights.

#### Live Example

[LIVE_PREVIEW: hero-section]

Create a full-width hero section:
- Full width, 400px height
- Background image with dark overlay (50% black)
- Centered white text: heading + subheading
- Rounded corners
- Use URL: `https://cdn.banatie.app/landing/demo/live/hero?prompt=aerial+view+modern+city+skyline+sunset+dramatic+lighting&aspectRatio=16:9`
- Heading: "Build the Future"
- Subheading: "Start your next project with AI-powered tools"

[/LIVE_PREVIEW]

#### Code Snippet

```html
<div class="relative w-full h-96 rounded-xl overflow-hidden">
  <img
    src="https://cdn.banatie.app/{org}/{project}/live/hero?prompt=abstract+tech+background&aspectRatio=16:9"
    alt="Hero background"
    class="w-full h-full object-cover"
  />
  <div class="absolute inset-0 bg-black/50 flex items-center justify-center">
    <h1 class="text-4xl font-bold text-white">Your Headline</h1>
  </div>
</div>
```

---

### Section: OG Image

**Aspect ratio:** `1200:630` (standard for social media)

**Use case:** Social sharing previews, Twitter/LinkedIn cards.

#### Live Example

[LIVE_PREVIEW: og-preview]

Create a social card preview mockup:
- Browser-like frame with URL bar showing "twitter.com"
- Inside: the OG image preview card
- Image with title overlay area
- Use URL: `https://cdn.banatie.app/landing/demo/live/og?prompt=abstract+gradient+purple+blue+tech+background&aspectRatio=1200:630`
- Show how it would appear as a link preview

[/LIVE_PREVIEW]

#### Code Snippet

```html
<head>
  <meta property="og:image" content="https://cdn.banatie.app/{org}/{project}/live/og?prompt=your+description&aspectRatio=1200:630" />
  <meta property="og:image:width" content="1200" />
  <meta property="og:image:height" content="630" />
  <meta name="twitter:card" content="summary_large_image" />
</head>
```

[TIP] OG images are crawled once and cached by social platforms. Change the prompt to generate a new image for updated content.

---

### Section: Features Block

**Aspect ratio:** `1:1`

**Use case:** Feature grids, benefit sections, service highlights.

#### Live Example

[LIVE_PREVIEW: features-grid]

Create a 3-column features section:
- Section heading: "Why Choose Us"
- 3 feature cards, each with:
  - Square illustration (64x64)
  - Feature title
  - Short description (1-2 lines)
- Use these:
  1. `?prompt=minimal+icon+illustration+lightning+bolt+speed+blue` — "Lightning Fast", "Deploy in seconds with our global CDN"
  2. `?prompt=minimal+icon+illustration+shield+security+green` — "Secure by Default", "Enterprise-grade security built in"
  3. `?prompt=minimal+icon+illustration+puzzle+piece+integration+purple` — "Easy Integration", "Works with your existing stack"

Base URL: `https://cdn.banatie.app/landing/demo/live/features` with `&aspectRatio=1:1`

[/LIVE_PREVIEW]

#### Code Snippet

```html
<div class="grid grid-cols-1 md:grid-cols-3 gap-8">
  <div class="text-center">
    <img
      src="https://cdn.banatie.app/{org}/{project}/live/features?prompt=icon+illustration&aspectRatio=1:1"
      alt="Feature"
      class="w-16 h-16 mx-auto rounded-lg"
    />
    <h3 class="mt-4 font-semibold">Feature Title</h3>
    <p class="mt-2 text-sm text-gray-600">Feature description goes here.</p>
  </div>
  <!-- Repeat for other features -->
</div>
```

---

### Section: File-based Workflow

Sometimes you need image files in your repository instead of URLs.

#### When to Use Files

- Next.js projects with `/public` folder
- Static site generators requiring local assets
- Version-controlled images
- Offline development

#### API Generation + Download

Generate an image and save it locally:

```javascript
// Node.js example
const fs = require('fs');

async function downloadPlaceholder(prompt, outputPath) {
  // Generate image
  const response = await fetch('https://api.banatie.app/v1/generations', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.BANATIE_API_KEY,
    },
    body: JSON.stringify({
      prompt: prompt,
      aspectRatio: '16:9',
    }),
  });

  const { image } = await response.json();

  // Download from CDN
  const imageResponse = await fetch(image.cdnUrl);
  const buffer = await imageResponse.arrayBuffer();

  // Save to file
  fs.writeFileSync(outputPath, Buffer.from(buffer));
  console.log(`Saved: ${outputPath}`);
}

// Usage
downloadPlaceholder(
  'modern office interior',
  './public/images/hero.png'
);
```

For full API reference, see [Generations API](/docs/api/generations/).

---

## Implementation Notes for Claude Code

### Live Preview Component

Create a new component `LivePreview` or similar wrapper that:
- Has dark background (slate-900 or similar)
- Shows the rendered example
- Has subtle border
- Optionally shows "Live Example" label

### Code Structure

```
/docs/guides/placeholder-images/
  page.tsx         ← Main guide page
```

Use existing doc components:
- `CodeBlock` for code snippets
- `Table` for parameter tables
- `TipBox` for tips
- `SectionHeader` for sections
- `Hero` for page header

### Image URLs

All live example images use:
```
https://cdn.banatie.app/landing/demo/live/{scope}?prompt=...&aspectRatio=...
```

Scopes used:
- `avatars` — avatar examples
- `products` — product photos
- `hero` — hero backgrounds
- `og` — OG images
- `features` — feature illustrations

---

## Verification

After implementation:
1. All live preview images load correctly
2. Code snippets are properly formatted
3. Links to other docs work
4. Page renders without errors
5. TOC navigation works
6. Mobile responsive

---

## Done Criteria

- [ ] Old guide deleted
- [ ] New guide created with all sections
- [ ] Live preview components render actual images
- [ ] Code snippets are copy-paste ready
- [ ] All internal links work
- [ ] No TypeScript/lint errors