- Traditional placeholder services give you gray rectangles or random photos - that have nothing to do with your actual content. + Two ways to generate placeholder images with Banatie:
-- With Banatie Live URLs, you describe what you need and get a relevant AI-generated image instantly. - Your mockups look real. Client demos make sense. Prototypes feel complete. +
-
+
-
+
+ Live URLs
+ {' '}
+ — describe what you need right in
<img> src URLs +
+ - + + API generation + {' '} + — full control, permanent URLs, downloadable files + +
+ All examples on this page use real placeholder image URLs generated by Banatie.
- -
+
+
+
+
+ Templates
++ Choose a style, get quality results. Banatie enhances your simple prompt based on + the selected template: +
+-
+
-
+
photorealistic — photo-quality images +
+ -
+
digital-art — stylized illustrations +
+ -
+
3d-render — 3D graphics +
+
+
+ Simple Prompts
++ Write minimal descriptions. Templates handle the rest: +
+-
+
- + → "office" becomes a detailed + modern office with proper lighting + +
- + → "headshot" becomes a + professional portrait with studio background + +
+ No need for complex prompts — this is for placeholders, not art. +
+
- Use a Live URL directly in your
Basic URL format:
- First request generates the image. Subsequent requests serve from cache instantly. -
-Example:
+
- Use the
Result:
+
+ Parameters:
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
+ 
@@ -175,141 +318,18 @@ export default function LiveUrlsPage() {
`}
- language="html"
- filename="Placeholder Examples"
- />
+ language="html"
+ filename="Placeholder Examples"
+ />
- 
-
-
-
-
-
-
- Use a Live URL directly in your
- First request generates the image. Subsequent requests serve from cache instantly. -
-
- Use the
- For dark UI interfaces, include dark theme hints in your prompt: -
- -
-
- Keywords like "dark background", "moody lighting", "dark theme", and "night mode" help generate dark-friendly images.
-
-
- - Generate realistic avatar placeholders for user profiles: -
- --
-
-
- •
- - Be specific --
- "modern minimalist office with plants" works better than "office". -
-
- -
- •
- - Include style hints --
- Add "photorealistic", "illustration", "3D render", or "flat design" for consistent style. -
-
- -
- •
- - Use scopes to organize --
- Group related placeholders: /live/avatars/, /live/products/, /live/backgrounds/. -
-
- -
- •
- - Same prompt = same image --
- Cached results mean consistent placeholders across your app. -
-
-
- Perfect for static sites, prototypes, and AI coding agents that generate HTML. -
-``` - -**Replace with:** -```tsx -- Perfect for placeholder images, prototypes, static sites, and AI coding agents. -
-``` - ---- - -## Verification - -After changes: -1. Run `pnpm dev` in `apps/landing` -2. Check homepage loads without errors -3. Inspect page source — verify new keywords in meta tag -4. Scroll to Prompt URLs section — verify updated text - ---- - -## Done criteria - -- [ ] Keywords array updated with 8 items -- [ ] PromptUrlsSection shows "placeholder images" first in list -- [ ] No TypeScript/lint errors -- [ ] Page renders correctly diff --git a/inbox/task-placeholder-guide-revision.md b/inbox/task-placeholder-guide-revision.md new file mode 100644 index 0000000..b047381 --- /dev/null +++ b/inbox/task-placeholder-guide-revision.md @@ -0,0 +1,267 @@ +# Task: Revise Placeholder Images Guide + +**Priority:** High +**Type:** Content revision +**Related:** Previous guide implementation needs text/UX improvements + +--- + +## Context + +Guide exists at `/docs/guides/placeholder-images/page.tsx`. Structure is OK, but texts need revision based on review session. This task covers text changes and minor UX improvements. + +--- + +## SEO Keywords to Include Naturally + +Target these in headings and body text: +- "placeholder image url" (390/mo, KD 21) +- "html placeholder image" (320/mo, KD 33) +- "placeholder image generator" (480/mo, KD 32) +- "ai placeholder images" (from our research) + +--- + +## Section-by-Section Changes + +### Hero + +**Current subtitle:** "Generate contextual images for development. Copy-paste ready examples with Tailwind CSS." + +**New subtitle:** "Generate contextual images for development. The new era of AI placeholders." + +Remove Tailwind mention from hero — it's implementation detail, not selling point. + +--- + +### What This Guide Covers + +**Current:** +- 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 + +**New:** +- **Live URLs** — describe what you need right in `
+```
+
+**Add live result** — show the actual generated image right after the code snippet.
+
+---
+
+### Organizing Placeholders
+
+**Current:** Dry list of scope examples
+
+**New approach:**
+
+Short explanation: "Organize images by sections of your site using scopes."
+
+One example showing the pattern:
+```
+/live/avatars?prompt=... → user photos
+/live/hero?prompt=... → hero backgrounds
+/live/products?prompt=... → product catalog
+```
+
+Then link: "Learn more about scopes in [Live URLs documentation](/docs/live-urls/#scopes)."
+
+Don't teach users how to name things — let them figure it out.
+
+---
+
+### Prompt Tips
+
+**Current "Be specific"** — contradicts placeholder philosophy
+
+**New "Write less, not more":**
+
+> For placeholders, simple prompts work best. Templates add the details.
+>
+> - Want an office? Write "office"
+> - Need something specific? Add only what matters: "office dark theme"
+> - Templates handle lighting, composition, style
+
+**Current "Dark mode"** → **"Colors and themes":**
+
+> Control the mood with color hints:
+> - `dark background` — dark theme
+> - `blue and orange accents` — specific palette
+> - `warm lighting` — cozy feel
+
+Keep dark mode examples but expand to general color control.
+
+**Remove "Consistent style"** — too vague. Consistency comes from templates + references (advanced topic).
+
+**Change TipBox text:**
+From: "All examples in this guide use prompt enhancement..."
+To: "Templates automatically enhance your prompts. A simple description becomes a detailed generation instruction."
+
+---
+
+### Recipes Section
+
+**Add section header:** Create a parent heading "Recipes" or "Common Use Cases" that groups all the examples (Avatar, Product, Hero, OG, Features).
+
+---
+
+### Recipe Cards: Code + Preview
+
+**UX improvement:** Each recipe should have a tabbed component with "Preview" and "Code" tabs, not separate blocks.
+
+If tabs are complex to implement, at minimum:
+- Show live preview FIRST
+- Code snippet below with clear label
+- Remove redundant "Code Snippet" / "Live Example" headings — visual separation is enough
+
+---
+
+### Testimonial Card (Avatar section)
+
+**Current design:** Basic dark card
+
+**Improve design quality:**
+- Add subtle border or gradient
+- Better typography hierarchy
+- Proper quote styling (quotation marks or left border)
+- Make it look like something you'd actually ship
+
+This is our showcase — it should look good.
+
+---
+
+### File-based Workflow
+
+**Current intro:** "Sometimes you need image files in your repository instead of URLs."
+
+**New intro:** "Need files in your repo? Here's how to download generated images."
+
+Warmer, more direct.
+
+**Remove "Static site generators" mention** — no SEO value, weak use case.
+
+**Keep:**
+- Next.js with imports (fix the pattern — show `import` from `src/assets`, not `/public`)
+- Version-controlled images
+
+**Simplify download example:**
+
+Current code is mini-SDK territory. Simplify to:
+
+```javascript
+// 1. 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: 'modern office' }),
+});
+
+const { image } = await response.json();
+console.log(image.cdnUrl); // Download this URL via browser or curl
+```
+
+Remove the fs.writeFileSync part — that's SDK territory. User can download via browser.
+
+---
+
+### "When to Use Files" List
+
+**Current:**
+- Next.js projects with `/public` folder ❌
+- Static site generators requiring local assets ❌
+- Version-controlled images
+- Offline development
+
+**New:**
+- Next.js/React projects with local image imports
+- Version-controlled placeholder assets
+- Offline or CI/CD environments
+
+---
+
+## Component Changes
+
+### LivePreview wrapper
+
+Current implementation is OK. No changes needed unless design quality is poor.
+
+### Code/Preview tabs
+
+If implementing tabs is too complex, skip for now. But note it as future improvement.
+
+---
+
+## Quality Checklist
+
+After implementation:
+- [ ] No mention of "Prompt Enhancement" as standalone feature
+- [ ] Templates positioned as primary feature
+- [ ] All example URLs use `sys/demo` (real project)
+- [ ] Quick Start shows actual generated image
+- [ ] File-based section uses import pattern, not /public
+- [ ] No static site generators mentioned
+- [ ] Testimonial card looks professional
+- [ ] SEO keywords naturally integrated
+
+---
+
+## Files to Modify
+
+```
+apps/landing/src/app/(apps)/docs/guides/placeholder-images/page.tsx
+```
+
+No new files needed.
diff --git a/inbox/task-placeholder-guide-rewrite.md b/inbox/task-placeholder-guide-rewrite.md
new file mode 100644
index 0000000..bbbb51b
--- /dev/null
+++ b/inbox/task-placeholder-guide-rewrite.md
@@ -0,0 +1,515 @@
+# 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
+
+```
+
+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
+
+```
+
+#### 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
+
+```
+
+#### 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
+
+ 
+
+```
+
+---
+
+### 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
+
+
+
+
+
+
+```
+
+[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
+
+
+
+Your Headline
+
+
+```
+
+---
+
+### 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
+ 
+
+
+
+ Feature Title
+Feature description goes here.
+