19 KiB
Banatie Documentation — Full Specification for Claude Code
Date: December 30, 2025
Purpose: Complete specification for generating documentation pages
Source of Truth: /docs/api/*.md in banatie-service repository
Target: /apps/landing/src/app/docs/
Documentation Spirit & Voice
This is critical. Every page must follow this approach:
Tone
- Technical but approachable — developers respect precision, but don't want to read a manual
- Confident, not arrogant — we know our product works, no need to oversell
- Direct — say what you mean, no fluff, no filler phrases
- Second person — "you", "your", not "the user" or "one"
Content Philosophy
- "Easy and simple" is the vibe — everything should feel lightweight
- Positive statements over negatives — say what we DO, not what we don't
- Show, don't tell — code examples over explanations
- One request, one result — emphasize simplicity of the flow
- Production-ready — everything we deliver is ready to ship, not a prototype
What to Avoid
- Filler phrases ("In this section we will discuss...")
- Marketing speak ("revolutionary", "game-changing", "cutting-edge")
- Unnecessary warnings and caveats
- Over-explaining simple concepts
- Walls of text without visual breaks
Visual Variety
Use callouts, tables, code blocks liberally. Break up text. Make pages scannable.
URL Structure (Final, SEO-Critical)
/docs # Getting Started
/docs/generation # Image Generation (main guide)
/docs/images # Working with Images
/docs/live-urls # Live URL Generation
/docs/authentication # API Keys & Auth (after live-urls)
/docs/api # API Reference Overview
/docs/api/generations # Generations endpoints
/docs/api/images # Images endpoints
/docs/api/flows # Flows endpoints
/docs/api/live-scopes # Live Scopes endpoints
10 pages total. URLs are permanent — do not change after deployment.
Sidebar Navigation
Two-level navigation:
Getting Started → /docs
Image Generation → /docs/generation
Working with Images → /docs/images
Live URLs → /docs/live-urls
Authentication → /docs/authentication
API Reference → /docs/api (expandable group)
├─ Overview → /docs/api
├─ Generations → /docs/api/generations
├─ Images → /docs/api/images
├─ Flows → /docs/api/flows
└─ Live Scopes → /docs/api/live-scopes
"API Reference" section is collapsible/expandable in sidebar.
Design System
Use existing components from the landing app. Key elements:
- Code blocks with syntax highlighting and copy button
- Tables for parameters, status codes, response fields
- Callout blocks:
- 💡 Tip — helpful hints, pro tips
- ⚠️ Warning — important cautions
- 📝 Note — additional context
- 🔒 Security — auth/security related
- Response blocks with status badges
- Card links for navigation to related pages
- Breadcrumbs for orientation
Visual variety is important — break up walls of text with callouts, tables, code examples.
Cross-Linking Strategy
Every guide page should link to corresponding API Reference section.
Every API Reference page should link back to the guide for context.
Examples:
/docs/generation→ "See full endpoint details in API Reference: Generations"/docs/api/generations→ "For concepts and examples, see Image Generation guide"
Page Specifications
Page 1: /docs — Getting Started
SEO Title: "Getting Started with Banatie API | AI Image Generation"
Meta Description: "Generate your first AI image in a few simple steps. REST API for production-ready image assets via CDN."
Purpose: First-time visitor lands here. Show them the value immediately.
CONTENT — USE EXACTLY AS WRITTEN:
# Get Started
Generate your first AI image in a few simple steps.
## What is Banatie?
Banatie is an image generation API for developers. Send a text prompt, get a production-ready image delivered via CDN.
Simple REST API. Optimized AI models that deliver consistent results. Images ready for production use immediately.
## Your First Image
Once you have your API key, generate an image with a single request:
```bash
curl -X POST https://api.banatie.app/api/v1/generations \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"prompt": "a friendly robot waving hello"}'
That's it. The response contains your image:
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "success",
"outputImage": {
"storageUrl": "https://cdn.banatie.app/my-org/my-project/img/8a3b2c1d-4e5f-6789-abcd-ef0123456789",
"width": 1792,
"height": 1008
}
}
}
Open storageUrl in your browser — there's your robot.
Production Ready
The image URL is permanent and served via global CDN. What this means for you:
- Fast access — images load in milliseconds
- Edge cached — served from locations closest to your users
- Global distribution — works fast everywhere in the world
One request. Production-ready result. Drop the URL into your app and ship.
Live URLs
Want to skip the API call entirely?
Generate images directly from a URL:
https://cdn.banatie.app/my-org/my-project/live/demo?prompt=a+friendly+robot+waving+hello
Put this in an <img src="..."> tag. First request generates the image, all subsequent requests serve it from cache instantly.
Perfect for placeholders, dynamic content, and rapid prototyping.
Get Your API Key
We're currently in early access. API keys are issued personally.
To request access:
- Go to banatie.app
- Enter your email in the signup form
- We'll send your API key within 24 hours
Next Steps
- Image Generation — Aspect ratios, prompt templates, using references
- Working with Images — Upload your own, organize with aliases
- Live URLs — Generate images directly from URL parameters
- API Reference — Full endpoint documentation
---
### Page 2: `/docs/generation` — Image Generation
**SEO Title:** "Image Generation | Banatie API Docs"
**Meta Description:** "Generate AI images from text prompts. Supports references, prompt templates, and chaining."
**Sections:**
1. **Basic Generation**
- POST /api/v1/generations
- Simple example: just prompt
- Response with status, outputImage, storageUrl
- Emphasize: one request → image ready
2. **Aspect Ratios**
- Table of supported ratios with use cases
- 1:1, 16:9, 9:16, 3:2, 21:9
3. **Prompt Templates**
- Templates improve your prompt for specific styles
- Available templates: general, photorealistic, illustration, minimalist, sticker, product, comic
- Example showing how template affects the result
- **Note callout:** Template selection coming soon. Currently uses general style.
4. **Using Reference Images**
- Add referenceImages array with image IDs
- Example with UUID reference
- **Pro Tip callout:** You can also use aliases like `@logo` instead of UUIDs. See [Working with Images](/docs/images) to learn about aliases.
- Auto-detection from prompt text (if you mention @alias in prompt)
5. **Continuing Generation**
- Pass the same flowId to chain generations
- Each response includes flowId for continuation
- Keep it brief, not a major feature highlight
6. **Regeneration**
- POST /api/v1/generations/:id/regenerate
- Same params, new image, same URL
**Link to:** `/docs/api/generations` for full endpoint reference
---
### Page 3: `/docs/images` — Working with Images
**SEO Title:** "Working with Images | Banatie API Docs"
**Meta Description:** "Upload, manage, and organize your images. CDN delivery, aliases, and image management."
**Sections:**
1. **Image URLs**
- All images served via CDN: `https://cdn.banatie.app/...`
- Format: `/{org}/{project}/img/{imageId}`
- Fast, cached, globally distributed
2. **Uploading Images**
- POST /api/v1/images/upload
- Multipart form data
- Use cases: brand assets, reference images, logos
3. **Listing & Getting Images**
- GET /api/v1/images
- GET /api/v1/images/:id
4. **Aliases**
- Assign memorable names to images
- Format: @alias-name (e.g., @logo, @hero-bg)
- PUT /api/v1/images/:id with alias field
- Access via CDN: `/{org}/{project}/img/@hero`
**Pro Tip callout:** Use aliases for brand assets like `@logo`, `@brand-colors`. Reference them in generations without remembering UUIDs.
5. **Deleting Images**
- DELETE /api/v1/images/:id
**Link to:** `/docs/api/images` for full endpoint reference
---
### Page 4: `/docs/live-urls` — Live URL Generation
**SEO Title:** "Live URLs | Banatie API Docs"
**Meta Description:** "Generate images directly from URL parameters. No API calls needed — just use the URL in your HTML."
**This is a highlight feature page — make it compelling but not salesy.**
**Sections:**
1. **The Concept**
- Generate images by putting prompt in URL
- Use directly in `<img src="...">`
- First request generates, subsequent requests serve from cache
2. **URL Format**
https://cdn.banatie.app/{org}/{project}/live/{scope}?prompt=...&aspectRatio=...
3. **Try It**
- Show a complete URL example they can open in browser
4. **Caching Behavior**
- Cache HIT: instant, from CDN edge
- Cache MISS: generates new image (few seconds)
- X-Cache-Status header tells you which
5. **Scopes**
- Organize live generations by scope
- Set limits per scope
- Auto-created on first use (if enabled)
6. **Rate Limits**
- 10 new generations per hour per IP
- Cache hits are unlimited
7. **Use Cases**
- Dynamic placeholders during development
- Personalized content
- Rapid prototyping
- HTML emails with dynamic images
**Link to:** `/docs/api/live-scopes` for scope management endpoints
---
### Page 5: `/docs/authentication` — Authentication
**SEO Title:** "Authentication | Banatie API Docs"
**Meta Description:** "How to authenticate with Banatie API using API keys."
**Sections:**
1. **Early Access**
- Currently in early access phase
- API keys are issued personally via email
- To request access: sign up on [banatie.app](https://banatie.app)
2. **Using Your API Key**
- All API requests require `X-API-Key` header
- Example: `curl -H "X-API-Key: your_key_here" ...`
- Keep your key secret, don't commit to git
3. **Key Types** (brief)
- Project Key: for your application
- Master Key: for admin operations (you probably don't need this)
**Note callout:** API key management dashboard coming soon. For now, contact us if you need to rotate your key.
**Link to:** `/docs/generation` as next step
---
### Page 6: `/docs/api` — API Reference Overview
**SEO Title:** "API Reference | Banatie API Docs"
**Meta Description:** "Complete REST API reference for Banatie. All endpoints, parameters, and response formats."
**This is a hub page — brief intro then links to subsections.**
**Sections:**
1. **Base URL**
2. **Authentication**
- All endpoints require `X-API-Key` header
- Link to `/docs/authentication`
3. **Response Format**
- Success: `{ "success": true, "data": {...} }`
- Error: `{ "success": false, "error": {...} }`
- Pagination pattern
4. **Common Error Codes**
- Table of HTTP status codes and meanings
5. **Rate Limits**
- 100 requests per hour
- Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
6. **Endpoints**
- Card links to each subsection:
- Generations — create and manage image generations
- Images — upload and organize images
- Flows — manage generation chains
- Live Scopes — control live URL generation
---
### Page 7: `/docs/api/generations` — Generations Endpoints
**SEO Title:** "Generations API | Banatie API Reference"
**Style:** Dry, complete, scannable. This is reference material.
**Endpoints to document:**
POST /api/v1/generations Create generation GET /api/v1/generations List generations GET /api/v1/generations/:id Get generation DELETE /api/v1/generations/:id Delete generation POST /api/v1/generations/:id/regenerate Regenerate PUT /api/v1/generations/:id Update generation
**For each endpoint:**
- Method + Path
- Description (1 line)
- Request parameters (table)
- Request body example (where applicable)
- Response example
- Notes if applicable
**Source:** Use `/docs/api/image-generation.md` and `/docs/api/image-generation-advanced.md`
**Important:** The API is synchronous. POST returns completed generation with outputImage immediately. Do NOT show polling flow.
**Link to:** `/docs/generation` for guide/context
---
### Page 8: `/docs/api/images` — Images Endpoints
**SEO Title:** "Images API | Banatie API Reference"
**Endpoints:**
POST /api/v1/images/upload Upload image GET /api/v1/images List images GET /api/v1/images/:id Get image (supports @alias) PUT /api/v1/images/:id Update image (set alias, metadata) DELETE /api/v1/images/:id Delete image
**CDN Endpoints (public, no auth):**
GET /cdn/{org}/{project}/img/{id} Get image by UUID GET /cdn/{org}/{project}/img/@{alias} Get image by alias
**Source:** Use `/docs/api/images-upload.md`
**Link to:** `/docs/images` for guide/context
---
### Page 9: `/docs/api/flows` — Flows Endpoints
**SEO Title:** "Flows API | Banatie API Reference"
**Brief intro:** Flows group related generations together. They're created automatically when you chain generations using the same flowId.
**Endpoints:**
GET /api/v1/flows List flows GET /api/v1/flows/:id Get flow GET /api/v1/flows/:id/generations List flow generations GET /api/v1/flows/:id/images List flow images PUT /api/v1/flows/:id/aliases Update flow aliases DELETE /api/v1/flows/:id/aliases/:alias Remove flow alias DELETE /api/v1/flows/:id Delete flow POST /api/v1/flows/:id/regenerate Regenerate last in flow
**Source:** Use `/docs/api/image-generation-advanced.md` section on flows
**Link to:** `/docs/generation` (section on continuing generations)
---
### Page 10: `/docs/api/live-scopes` — Live Scopes Endpoints
**SEO Title:** "Live Scopes API | Banatie API Reference"
**Endpoints:**
POST /api/v1/live/scopes Create scope GET /api/v1/live/scopes List scopes GET /api/v1/live/scopes/:slug Get scope PUT /api/v1/live/scopes/:slug Update scope DELETE /api/v1/live/scopes/:slug Delete scope POST /api/v1/live/scopes/:slug/regenerate Regenerate scope images
**CDN Live Endpoint (public):**
GET /cdn/{org}/{project}/live/{scope}?prompt=... Live generation
Query parameters: prompt (required), aspectRatio, autoEnhance, template
**Source:** Use `/docs/api/live-url.md`
**Link to:** `/docs/live-urls` for guide/context
---
## Implementation Notes for Claude Code
1. **Use existing components** — Check `/apps/landing/src/app/docs/` for current implementation patterns
2. **Correct URLs everywhere:**
- API: `https://api.banatie.app`
- CDN: `https://cdn.banatie.app`
- NOT `.com` — always `.app`
3. **Example paths use:** `my-org/my-project` (not `default/my-project`)
4. **No SDK references** — We don't have SDK yet. Don't mention it.
5. **API is synchronous** — POST /generations returns completed result immediately. No polling.
6. **Prompt templates, not "enhancement"** — We have templates that improve prompts. Don't call it "auto-enhance" as a standalone feature.
7. **Breadcrumbs:** Every page should show path (e.g., "Docs > API Reference > Generations")
8. **Meta tags:** Each page needs proper SEO title and description as specified
9. **Mobile responsive** — Documentation must work well on mobile
10. **Code examples:** Use `bash` (curl) as primary. Show request AND response for every endpoint.
11. **Image dimensions in examples:** Use 1792 x 1008 (16:9) not 1024 x 1024
---
## File Structure Expected
apps/landing/src/app/docs/ ├── page.tsx # /docs (Get Started) ├── generation/ │ └── page.tsx # /docs/generation ├── images/ │ └── page.tsx # /docs/images ├── live-urls/ │ └── page.tsx # /docs/live-urls ├── authentication/ │ └── page.tsx # /docs/authentication └── api/ ├── page.tsx # /docs/api (Overview) ├── generations/ │ └── page.tsx # /docs/api/generations ├── images/ │ └── page.tsx # /docs/api/images ├── flows/ │ └── page.tsx # /docs/api/flows └── live-scopes/ └── page.tsx # /docs/api/live-scopes
---
## Priority Order for Implementation
1. `/docs` — Get Started (content provided above)
2. `/docs/generation` — Core feature
3. `/docs/api` — Reference hub
4. `/docs/api/generations` — Most used endpoints
5. `/docs/images` — Working with results
6. `/docs/api/images` — Image endpoints
7. `/docs/live-urls` — Highlight feature
8. `/docs/api/live-scopes` — Live management
9. `/docs/authentication` — Auth info
10. `/docs/api/flows` — Least priority (advanced users)
---
## Quality Checklist
Before marking complete, verify:
- [ ] All URLs use `banatie.app` (not `.com`)
- [ ] Example paths use `my-org/my-project`
- [ ] Image dimensions are 1792 x 1008 in examples
- [ ] All code examples are copy-paste ready
- [ ] Every endpoint shows request AND response
- [ ] Tables render correctly
- [ ] Callout blocks used for visual variety
- [ ] Cross-links between guide and reference pages
- [ ] Sidebar navigation matches URL structure
- [ ] Breadcrumbs work on all pages
- [ ] Mobile rendering is acceptable
- [ ] No references to SDK or features that don't exist
- [ ] No polling/async flow — API is synchronous
- [ ] SEO titles and descriptions set for all pages
- [ ] Tone matches "Documentation Spirit" section
---
**End of Specification**