usulpro
/
banatie-service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc: save task

This commit is contained in:
Oleg Proskurin 2025-12-31 01:28:10 +07:00
parent 3e490d1dd9
commit 8e315ffe01
1 changed files with 606 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

606
documentation-section-task.md Normal file
View File

@ -0,0 +1,606 @@
# 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)"
- `/docs/api/generations` → "For concepts and examples, see [Image Generation guide](/docs/generation)"
---
## 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:**
```markdown
# 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:
```json
{
"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.
→ **[Learn more about Live URLs](/docs/live-urls)**
## Get Your API Key
We're currently in early access. API keys are issued personally.
**To request access:**
1. Go to [banatie.app](https://banatie.app)
2. Enter your email in the signup form
3. We'll send your API key within 24 hours
## Next Steps
- **[Image Generation](/docs/generation)** — Aspect ratios, prompt templates, using references
- **[Working with Images](/docs/images)** — Upload your own, organize with aliases
- **[Live URLs](/docs/live-urls)** — Generate images directly from URL parameters
- **[API Reference](/docs/api)** — 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**
```
https://api.banatie.app
```
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**