diff --git a/apps/landing/src/app/docs/api/flows/page.tsx b/apps/landing/src/app/docs/api/flows/page.tsx new file mode 100644 index 0000000..92b356e --- /dev/null +++ b/apps/landing/src/app/docs/api/flows/page.tsx @@ -0,0 +1,334 @@ +'use client'; + +import { TipBox } from '@/components/docs/shared/TipBox'; +import { Table } from '@/components/docs/shared/Table'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { + Hero, + SectionHeader, + InlineCode, + EndpointCard, + ResponseBlock, +} from '@/components/docs/blocks'; + +const tocItems = [ + { id: 'overview', text: 'Overview', level: 2 }, + { id: 'list-flows', text: 'List Flows', level: 2 }, + { id: 'get-flow', text: 'Get Flow', level: 2 }, + { id: 'list-flow-generations', text: 'List Flow Generations', level: 2 }, + { id: 'list-flow-images', text: 'List Flow Images', level: 2 }, + { id: 'update-flow-aliases', text: 'Update Flow Aliases', level: 2 }, + { id: 'remove-flow-alias', text: 'Remove Flow Alias', level: 2 }, + { id: 'regenerate-flow', text: 'Regenerate Flow', level: 2 }, + { id: 'delete-flow', text: 'Delete Flow', level: 2 }, + { id: 'next-steps', text: 'Next Steps', level: 2 }, +]; + +export default function FlowsAPIPage() { + return ( + + + +
+ + Overview + +

+ Flows group related generations together. They're created automatically when you chain generations using the same flowId. +

+

+ Flows also support flow-scoped aliases — named references to images that are unique within a flow but don't conflict with project-level aliases. +

+
+ +
+ + List Flows + +

+ Retrieve all flows for your project with computed counts. +

+ + + +
+

Query Parameters

+ limit, 'number', 'Results per page (default: 20, max: 100)'], + [offset, 'number', 'Number of results to skip'], + ]} + /> + + +
+

Example Request

+ +
+ +
+

Response

+ +
+ + +
+ + Get Flow + +

+ Retrieve a single flow with detailed statistics. +

+ + + +
+

Example Request

+ +
+
+ +
+ + List Flow Generations + +

+ Retrieve all generations in a specific flow. +

+ + + +
+

Example Request

+ +
+
+ +
+ + List Flow Images + +

+ Retrieve all images (generated and uploaded) in a flow. +

+ + + +
+

Example Request

+ +
+
+ +
+ + Update Flow Aliases + +

+ Add or update flow-scoped aliases. Aliases are merged with existing ones. +

+ + + +
+

Request Body

+
aliases, 'object', 'Key-value pairs of aliases to add/update'], + ]} + /> + + +
+

Example Request

+ +
+ + +
+ + Remove Flow Alias + +

+ Remove a specific alias from a flow. +

+ + + +
+

Example Request

+ +
+
+ +
+ + Regenerate Flow + +

+ Regenerate the most recent generation in the flow. +

+ + + +
+

Example Request

+ +
+
+ +
+ + Delete Flow + +

+ Delete a flow with cascade deletion. Images with project aliases are preserved. +

+ + + +
+

Example Request

+ +
+ +
+ + Deleting a flow removes all generations and images in it. Images with project aliases are preserved (unlinked from the flow). + +
+
+ + ); +} diff --git a/apps/landing/src/app/docs/api/generations/page.tsx b/apps/landing/src/app/docs/api/generations/page.tsx new file mode 100644 index 0000000..331ad0b --- /dev/null +++ b/apps/landing/src/app/docs/api/generations/page.tsx @@ -0,0 +1,326 @@ +'use client'; + +import { TipBox } from '@/components/docs/shared/TipBox'; +import { Table } from '@/components/docs/shared/Table'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { + Hero, + SectionHeader, + InlineCode, + EndpointCard, + ResponseBlock, +} from '@/components/docs/blocks'; + +const tocItems = [ + { id: 'create-generation', text: 'Create Generation', level: 2 }, + { id: 'list-generations', text: 'List Generations', level: 2 }, + { id: 'get-generation', text: 'Get Generation', level: 2 }, + { id: 'update-generation', text: 'Update Generation', level: 2 }, + { id: 'regenerate', text: 'Regenerate', level: 2 }, + { id: 'delete-generation', text: 'Delete Generation', level: 2 }, + { id: 'next-steps', text: 'Next Steps', level: 2 }, +]; + +export default function GenerationsAPIPage() { + return ( + + + +
+ + Create Generation + +

+ Generate a new image from a text prompt. +

+ + + +
+

Request Body

+
prompt, + string, + Yes, + 'Text description of the image to generate', + ], + [ + aspectRatio, + string, + No, + '1:1, 16:9, 9:16, 3:2, 21:9 (default: 1:1)', + ], + [ + referenceImages, + string[], + No, + 'Array of image IDs or @aliases to use as references', + ], + [ + flowId, + string, + No, + 'Associate with existing flow', + ], + [ + alias, + string, + No, + 'Project-scoped alias (@custom-name)', + ], + [ + autoEnhance, + boolean, + No, + 'Enable prompt enhancement (default: true)', + ], + [ + meta, + object, + No, + 'Custom metadata', + ], + ]} + /> + + +
+

Example Request

+ +
+ +
+

Response

+ +
+ + +
+ + List Generations + +

+ Retrieve all generations for your project with optional filtering. +

+ + + +
+

Query Parameters

+
flowId, 'string', 'Filter by flow ID'], + [status, 'string', 'Filter by status: pending, processing, success, failed'], + [limit, 'number', 'Results per page (default: 20, max: 100)'], + [offset, 'number', 'Number of results to skip'], + ]} + /> + + +
+

Example Request

+ +
+ + +
+ + Get Generation + +

+ Retrieve a single generation by ID. +

+ + + +
+

Example Request

+ +
+
+ +
+ + Update Generation + +

+ Update generation parameters. Changing prompt or aspectRatio triggers automatic regeneration. +

+ + + +
+

Request Body

+
prompt, 'string', 'New prompt (triggers regeneration)'], + [aspectRatio, 'string', 'New aspect ratio (triggers regeneration)'], + [flowId, 'string | null', 'Change flow association'], + [meta, 'object', 'Update custom metadata'], + ]} + /> + + +
+ + Changing prompt or aspectRatio triggers a new generation. The image ID and URL remain the same — only the content changes. + +
+ + +
+ + Regenerate + +

+ Create a new image using the exact same parameters. Useful for getting a different result or recovering from failures. +

+ + + +
+

Example Request

+ +
+
+ +
+ + Delete Generation + +

+ Delete a generation and its output image. Images with project aliases are preserved. +

+ + + +
+

Example Request

+ +
+ +
+

Response

+ +
+
+ + ); +} diff --git a/apps/landing/src/app/docs/api/images/page.tsx b/apps/landing/src/app/docs/api/images/page.tsx new file mode 100644 index 0000000..ae98cde --- /dev/null +++ b/apps/landing/src/app/docs/api/images/page.tsx @@ -0,0 +1,361 @@ +'use client'; + +import { TipBox } from '@/components/docs/shared/TipBox'; +import { Table } from '@/components/docs/shared/Table'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { + Hero, + SectionHeader, + InlineCode, + EndpointCard, + ResponseBlock, +} from '@/components/docs/blocks'; + +const tocItems = [ + { id: 'upload-image', text: 'Upload Image', level: 2 }, + { id: 'list-images', text: 'List Images', level: 2 }, + { id: 'get-image', text: 'Get Image', level: 2 }, + { id: 'update-image', text: 'Update Image', level: 2 }, + { id: 'assign-alias', text: 'Assign Alias', level: 2 }, + { id: 'delete-image', text: 'Delete Image', level: 2 }, + { id: 'cdn-endpoints', text: 'CDN Endpoints', level: 2 }, + { id: 'next-steps', text: 'Next Steps', level: 2 }, +]; + +export default function ImagesAPIPage() { + return ( + + + +
+ + Upload Image + +

+ Upload an image file to your project storage. +

+ + + +
+

Form Data

+
file, + file, + Yes, + 'Image file (max 5MB, JPEG/PNG/WebP)', + ], + [ + alias, + string, + No, + 'Project-scoped alias (@custom-name)', + ], + [ + flowId, + string, + No, + 'Associate with flow', + ], + [ + meta, + string, + No, + 'Custom metadata (JSON string)', + ], + ]} + /> + + +
+

Example Request

+ +
+ +
+

Response

+ +
+ + +
+ + List Images + +

+ Retrieve all images in your project with optional filtering. +

+ + + +
+

Query Parameters

+
flowId, 'string', 'Filter by flow ID'], + [source, 'string', 'Filter by source: generated, uploaded'], + [alias, 'string', 'Filter by exact alias match'], + [limit, 'number', 'Results per page (default: 20, max: 100)'], + [offset, 'number', 'Number of results to skip'], + ]} + /> + + +
+

Example Request

+ +
+ + +
+ + Get Image + +

+ Retrieve a single image by ID or alias. +

+ + + +
+

Example Requests

+ +
+
+ +
+ + Update Image + +

+ Update image metadata (focal point and custom metadata). +

+ + + +
+

Request Body

+
focalPoint, 'object', 'Focal point for cropping {x: 0-1, y: 0-1}'], + [meta, 'object', 'Custom metadata'], + ]} + /> + + +
+

Example Request

+ +
+ + +
+ + Assign Alias + +

+ Assign or remove a project-scoped alias from an image. +

+ + + +
+

Request Body

+
alias, 'string | null', 'Alias to assign (@name) or null to remove'], + ]} + /> + + +
+

Example Requests

+ +
+ + +
+ + Delete Image + +

+ Permanently delete an image from storage. +

+ + + +
+

Example Request

+ +
+ +
+ + Deletion is permanent. The image file and all references are removed from storage. + +
+
+ +
+ + CDN Endpoints + +

+ Access images directly via CDN (public, no authentication required): +

+ +
+
+

By Image ID

+ +
+ +
+

By Alias

+ +
+
+ +
+ + CDN URLs are public and don't require authentication. They return image bytes directly with appropriate caching headers. + +
+
+ + ); +} diff --git a/apps/landing/src/app/docs/api/live-scopes/page.tsx b/apps/landing/src/app/docs/api/live-scopes/page.tsx new file mode 100644 index 0000000..3b6e8ef --- /dev/null +++ b/apps/landing/src/app/docs/api/live-scopes/page.tsx @@ -0,0 +1,419 @@ +'use client'; + +import { TipBox } from '@/components/docs/shared/TipBox'; +import { Table } from '@/components/docs/shared/Table'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { + Hero, + SectionHeader, + InlineCode, + EndpointCard, + ResponseBlock, +} from '@/components/docs/blocks'; + +const tocItems = [ + { id: 'overview', text: 'Overview', level: 2 }, + { id: 'create-scope', text: 'Create Scope', level: 2 }, + { id: 'list-scopes', text: 'List Scopes', level: 2 }, + { id: 'get-scope', text: 'Get Scope', level: 2 }, + { id: 'update-scope', text: 'Update Scope', level: 2 }, + { id: 'regenerate-scope', text: 'Regenerate Scope', level: 2 }, + { id: 'delete-scope', text: 'Delete Scope', level: 2 }, + { id: 'cdn-live-endpoint', text: 'CDN Live Endpoint', level: 2 }, + { id: 'next-steps', text: 'Next Steps', level: 2 }, +]; + +export default function LiveScopesAPIPage() { + return ( + + + +
+ + Overview + +

+ Live scopes organize live URL generations. Each scope has its own generation limit and can be configured independently. +

+

+ Scopes are auto-created on first use, but you can pre-configure them via this API to set custom limits. +

+
+ +
+ + Create Scope + +

+ Create a new live scope with custom settings. +

+ + + +
+

Request Body

+
slug, + string, + Yes, + 'Unique scope identifier (alphanumeric + hyphens + underscores)', + ], + [ + allowNewGenerations, + boolean, + No, + 'Allow new generations (default: true)', + ], + [ + newGenerationsLimit, + number, + No, + 'Maximum generations allowed (default: 30)', + ], + [ + meta, + object, + No, + 'Custom metadata', + ], + ]} + /> + + +
+

Example Request

+ +
+ +
+

Response

+ +
+ + +
+ + List Scopes + +

+ Retrieve all live scopes for your project. +

+ + + +
+

Query Parameters

+
slug, 'string', 'Filter by exact slug match'], + [limit, 'number', 'Results per page (default: 20, max: 100)'], + [offset, 'number', 'Number of results to skip'], + ]} + /> + + +
+

Example Request

+ +
+ + +
+ + Get Scope + +

+ Retrieve a single scope with statistics. +

+ + + +
+

Example Request

+ +
+
+ +
+ + Update Scope + +

+ Update scope settings. Changes take effect immediately. +

+ + + +
+

Request Body

+
allowNewGenerations, 'boolean', 'Allow/disallow new generations'], + [newGenerationsLimit, 'number', 'Update generation limit'], + [meta, 'object', 'Update custom metadata'], + ]} + /> + + +
+

Example Request

+ +
+ + +
+ + Regenerate Scope + +

+ Regenerate images in a scope. Can regenerate a specific image or all images. +

+ + + +
+

Request Body

+
imageId, 'string', 'Specific image to regenerate (omit for all)'], + ]} + /> + + +
+

Example Requests

+ +
+ +
+

Response

+ +
+ + +
+ + Delete Scope + +

+ Delete a scope and all its cached images. +

+ + + +
+

Example Request

+ +
+ +
+ + Deleting a scope permanently removes all cached images in it. This cannot be undone. + +
+
+ +
+ + CDN Live Endpoint + +

+ Public endpoint for live URL generation (no authentication required): +

+ + + +
+

Query Parameters

+
prompt, + Yes, + 'Text description of the image to generate', + ], + [ + aspectRatio, + No, + 'Image ratio (default: 1:1)', + ], + [ + autoEnhance, + No, + 'Enable prompt enhancement', + ], + [ + template, + No, + 'Enhancement template to use', + ], + ]} + /> + + +
+

Example

+ +
+ +
+

Response Headers

+
X-Cache-Status, 'HIT (cached) or MISS (generated)'], + [X-Scope, 'Scope identifier'], + [X-Image-Id, 'Image UUID'], + [X-RateLimit-Remaining, 'Remaining IP rate limit (on MISS)'], + ]} + /> + + + + ); +} diff --git a/apps/landing/src/app/docs/api/page.tsx b/apps/landing/src/app/docs/api/page.tsx new file mode 100644 index 0000000..13c1adc --- /dev/null +++ b/apps/landing/src/app/docs/api/page.tsx @@ -0,0 +1,239 @@ +'use client'; + +import { TipBox } from '@/components/docs/shared/TipBox'; +import { Table } from '@/components/docs/shared/Table'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { + Hero, + SectionHeader, + InlineCode, + LinkCard, + LinkCardGrid, +} from '@/components/docs/blocks'; + +const tocItems = [ + { id: 'base-url', text: 'Base URL', level: 2 }, + { id: 'authentication', text: 'Authentication', level: 2 }, + { id: 'response-format', text: 'Response Format', level: 2 }, + { id: 'error-codes', text: 'Common Error Codes', level: 2 }, + { id: 'rate-limits', text: 'Rate Limits', level: 2 }, + { id: 'endpoints', text: 'Endpoints', level: 2 }, + { id: 'next-steps', text: 'Next Steps', level: 2 }, +]; + +export default function APIOverviewPage() { + return ( + + + +
+ + Base URL + + + +
+ +
+ + Authentication + +

+ All endpoints require the X-API-Key header: +

+ + + +

+ See Authentication for details on obtaining and using API keys. +

+
+ +
+ + Response Format + +

+ All responses follow a consistent JSON structure: +

+ +
+
+

Success Response:

+ +
+ +
+

Error Response:

+ +
+ +
+

Paginated Response:

+ +
+
+
+ +
+ + Common Error Codes + + +
400, + 'VALIDATION_ERROR', + 'Missing or invalid parameters', + ], + [ + 401, + 'UNAUTHORIZED', + 'Missing or invalid API key', + ], + [ + 404, + '*_NOT_FOUND', + 'Requested resource not found', + ], + [ + 409, + 'ALIAS_CONFLICT', + 'Alias already exists', + ], + [ + 429, + 'RATE_LIMIT_EXCEEDED', + 'Too many requests', + ], + [ + 500, + 'INTERNAL_ERROR', + 'Server error', + ], + ]} + /> + + +
+ + Rate Limits + +

+ API requests are rate limited to 100 requests per hour per API key. +

+

+ Rate limit headers are included in every response: +

+ +
X-RateLimit-Limit, 'Maximum requests per hour'], + [X-RateLimit-Remaining, 'Requests remaining in current window'], + [X-RateLimit-Reset, 'Unix timestamp when limit resets'], + ]} + /> + + +
+ + Endpoints + + + + + + + + +
+ + ); +} diff --git a/apps/landing/src/app/docs/api/text-to-image/page.tsx b/apps/landing/src/app/docs/api/text-to-image/page.tsx deleted file mode 100644 index 0d5fb8a..0000000 --- a/apps/landing/src/app/docs/api/text-to-image/page.tsx +++ /dev/null @@ -1,226 +0,0 @@ -'use client'; - -/** - * API Reference: Text to Image - * - * Refactored to use DocPage component for consistent layout - * Layout handles SubsectionNav and Left Sidebar - * DocPage handles Breadcrumb, Article structure, Next Steps, and TOC - * This page provides only the content (Hero + sections) - */ - -import { TipBox } from '@/components/docs/shared/TipBox'; -import { Table } from '@/components/docs/shared/Table'; -import { CodeBlock } from '@/components/docs/shared/CodeBlock'; -import { DocPage } from '@/components/docs/layout/DocPage'; -import { InteractiveAPIWidget } from '@/components/docs/blocks/InteractiveAPIWidget'; -import { - Hero, - SectionHeader, - InlineCode, - EndpointCard, -} from '@/components/docs/blocks'; - -const tocItems = [ - { id: 'overview', text: 'Overview', level: 2 }, - { id: 'endpoint', text: 'Endpoint', level: 2 }, - { id: 'parameters', text: 'Parameters', level: 2 }, - { id: 'response', text: 'Response', level: 2 }, - { id: 'error-codes', text: 'Error Codes', level: 2 }, - { id: 'interactive', text: 'Try It Live', level: 2 }, - { id: 'next-steps', text: 'Next Steps', level: 2 }, -]; - -const parameters = [ - { name: 'prompt', type: 'string', required: true, description: 'Text description of the image to generate' }, - { name: 'filename', type: 'string', required: false, description: 'Output filename (without extension)' }, - { name: 'aspectRatio', type: 'string', required: false, description: 'Image aspect ratio: "1:1", "16:9", "9:16", "4:3"' }, - { name: 'autoEnhance', type: 'boolean', required: false, description: 'Enable AI prompt enhancement for better results' }, -]; - -export default function TextToImageAPIPage() { - return ( - - - {/* Hero Section */} - - - {/* Overview */} -
- - Overview - -

- The Text to Image endpoint allows you to generate images from natural language descriptions. - Powered by Google Gemini 2.5 Flash and Imagen 4.0, it produces photorealistic images - optimized for your specified requirements. -

- - Tip: Enable autoEnhance - to let AI improve your prompts for better image quality. - -
- - {/* Endpoint */} -
- - Endpoint - - -
- - {/* Parameters */} -
- - Parameters - -

- All parameters should be sent in the request body as JSON. -

- -
[ - {param.name}, - {param.type}, - - {param.required ? 'Yes' : 'No'} - , - param.description, - ])} - /> - -
- - Default Values: If not specified, filename is - auto-generated, aspectRatio defaults - to "1:1", and autoEnhance is false. - -
- - - {/* Response */} -
- - Response - -

- On success, the API returns a JSON object containing the generated image URL and metadata. -

- - -
- - {/* Error Codes */} -
- - Error Codes - -

- The API uses standard HTTP status codes and returns descriptive error messages. -

- -
400, - 'Bad Request', - 'Missing or invalid parameters in the request body', - ], - [ - 401, - 'Unauthorized', - 'Missing or invalid API key in X-API-Key header', - ], - [ - 429, - 'Rate Limit', - 'Too many requests. Check rate limit headers for retry timing', - ], - [ - 500, - 'Server Error', - 'Internal server error. Contact support if persists', - ], - ]} - /> - -
- - Rate Limits: Project API keys are limited to 100 requests per hour. - Upgrade your plan for higher limits. - -
- - - {/* Interactive Widget */} -
- - Try It Live - -

- Test the API directly from this page. Enter your API key and customize the parameters below. -

- - -
- - - ); -} diff --git a/apps/landing/src/app/docs/authentication/page.tsx b/apps/landing/src/app/docs/authentication/page.tsx new file mode 100644 index 0000000..190e315 --- /dev/null +++ b/apps/landing/src/app/docs/authentication/page.tsx @@ -0,0 +1,124 @@ +'use client'; + +import { TipBox } from '@/components/docs/shared/TipBox'; +import { Table } from '@/components/docs/shared/Table'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { + Hero, + SectionHeader, + InlineCode, +} from '@/components/docs/blocks'; + +const tocItems = [ + { id: 'early-access', text: 'Early Access', level: 2 }, + { id: 'using-your-api-key', text: 'Using Your API Key', level: 2 }, + { id: 'key-types', text: 'Key Types', level: 2 }, + { id: 'next-steps', text: 'Next Steps', level: 2 }, +]; + +export default function AuthenticationPage() { + return ( + + + +
+ + Early Access + +

+ We're currently in early access phase. API keys are issued personally via email. +

+

+ To request access: Sign up at banatie.app. We'll send your API key within 24 hours. +

+
+ +
+ + Using Your API Key + +

+ All API requests require the X-API-Key header: +

+ + + +
+ + Keep your API key secure. Don't commit it to version control or expose it in client-side code. Use environment variables in your applications. + +
+
+ +
+ + Key Types + +

+ Banatie uses two types of API keys: +

+ +
Project Key, + 'Image generation, uploads, images', + 90 days, + 'Your application integration', + ], + [ + Master Key, + 'Full admin access, key management', + Never expires, + 'Server-side admin operations', + ], + ]} + /> + +

+ You'll receive a Project Key for your application. Master Keys are for administrative operations — you probably don't need one. +

+ +
+ + API key management dashboard coming soon. For now, contact us if you need to rotate your key. + +
+ + + ); +} diff --git a/apps/landing/src/app/docs/generation/page.tsx b/apps/landing/src/app/docs/generation/page.tsx new file mode 100644 index 0000000..db9fb61 --- /dev/null +++ b/apps/landing/src/app/docs/generation/page.tsx @@ -0,0 +1,263 @@ +'use client'; + +import { TipBox } from '@/components/docs/shared/TipBox'; +import { Table } from '@/components/docs/shared/Table'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { + Hero, + SectionHeader, + InlineCode, + ResponseBlock, +} from '@/components/docs/blocks'; + +const tocItems = [ + { id: 'basic-generation', text: 'Basic Generation', level: 2 }, + { id: 'aspect-ratios', text: 'Aspect Ratios', level: 2 }, + { id: 'prompt-templates', text: 'Prompt Templates', level: 2 }, + { id: 'reference-images', text: 'Using Reference Images', level: 2 }, + { id: 'continuing-generation', text: 'Continuing Generation', level: 2 }, + { id: 'regeneration', text: 'Regeneration', level: 2 }, + { id: 'next-steps', text: 'Next Steps', level: 2 }, +]; + +export default function GenerationPage() { + return ( + + + +
+ + Basic Generation + +

+ Generate an image by sending a text prompt to the generations endpoint: +

+ + + +

+ The response contains your generated image immediately: +

+ + + +

+ One request, one result. The storageUrl is your production-ready image, served via CDN. +

+
+ +
+ + Aspect Ratios + +

+ Choose the aspect ratio that fits your use case: +

+ +
1:1, + '1024 x 1024', + 'Social media posts, profile pictures, thumbnails', + ], + [ + 16:9, + '1792 x 1008', + 'Blog headers, presentations, video thumbnails', + ], + [ + 9:16, + '1008 x 1792', + 'Stories, mobile backgrounds, vertical banners', + ], + [ + 3:2, + '1536 x 1024', + 'Photography-style images, print layouts', + ], + [ + 21:9, + '2016 x 864', + 'Ultra-wide banners, cinematic headers', + ], + ]} + /> + +

+ Default is 1:1 if not specified. +

+ + +
+ + Prompt Templates + +

+ Templates improve your prompt for specific styles. Available templates: +

+ +
general, 'Balanced style for most use cases'], + [photorealistic, 'Photo-like realism with natural lighting'], + [illustration, 'Artistic illustration style'], + [minimalist, 'Clean, simple compositions'], + [sticker, 'Sticker-style with clear edges'], + [product, 'E-commerce product photography'], + [comic, 'Comic book visual style'], + ]} + /> + +
+ + Template selection coming soon. Currently uses general style for all generations. + +
+ + +
+ + Using Reference Images + +

+ Add reference images for style guidance or context. Pass image IDs or aliases in the referenceImages array: +

+ + + +
+ + Pro Tip: Use aliases like @logo instead of UUIDs. See Working with Images to learn about aliases. + +
+ +

+ You can also mention aliases directly in your prompt text — they're auto-detected: +

+ + +
+ +
+ + Continuing Generation + +

+ Chain multiple generations together by passing the same flowId: +

+ + + +

+ Each response includes a flowId you can use to continue the sequence. Flows help organize related generations together. +

+
+ +
+ + Regeneration + +

+ Want a different result with the same parameters? Regenerate an existing generation: +

+ + + +

+ Same prompt, new image. The generation ID and URL stay the same — the image content is replaced. +

+
+ + ); +} diff --git a/apps/landing/src/app/docs/guides/authentication/page.tsx b/apps/landing/src/app/docs/guides/authentication/page.tsx deleted file mode 100644 index e05dac7..0000000 --- a/apps/landing/src/app/docs/guides/authentication/page.tsx +++ /dev/null @@ -1,313 +0,0 @@ -'use client'; - -/** - * Authentication Guide - * - * Refactored to use DocPage component for consistent layout - * Layout handles SubsectionNav and Left Sidebar - * DocPage handles Breadcrumb, Article structure, Next Steps, and TOC - * This page provides only the content (Hero + sections) - */ - -import { TipBox } from '@/components/docs/shared/TipBox'; -import { Table } from '@/components/docs/shared/Table'; -import { CodeBlock } from '@/components/docs/shared/CodeBlock'; -import { DocPage } from '@/components/docs/layout/DocPage'; -import { - Hero, - SectionHeader, - InlineCode, -} from '@/components/docs/blocks'; - -const tocItems = [ - { id: 'overview', text: 'Overview', level: 2 }, - { id: 'api-keys', text: 'API Keys', level: 2 }, - { id: 'key-types', text: 'Key Types', level: 3 }, - { id: 'creating-keys', text: 'Creating Keys', level: 3 }, - { id: 'using-keys', text: 'Using API Keys', level: 2 }, - { id: 'rate-limits', text: 'Rate Limits', level: 2 }, - { id: 'security', text: 'Security Best Practices', level: 2 }, - { id: 'next-steps', text: 'Next Steps', level: 2 }, -]; - -export default function AuthenticationGuidePage() { - return ( - - - {/* Hero Section */} - - - {/* Overview */} -
- - Overview - -

- Banatie uses API keys to authenticate requests. All API endpoints require authentication - via the X-API-Key header. - API keys are tied to organizations and projects, providing fine-grained access control. -

- - - Quick Start: New to API authentication? Check out our{' '} - - Getting Started guide - {' '} - for a step-by-step walkthrough. - -
- - {/* API Keys */} -
- - API Keys - - -
- - Key Types - -

- Banatie supports two types of API keys, each with different permissions and use cases: -

- -
Master Key, - 'Full admin access, can create/revoke keys', - Never expires, - 'Server-side admin operations, key management', - ], - [ - Project Key, - 'Image generation only', - 90 days, - 'Application integration, API requests', - ], - ]} - /> - -
- - Master Key Security: Master keys have full - administrative access and never expire. Store them securely in encrypted vaults or - secret managers. Never expose master keys in client-side code, logs, or version control. - Use project keys for application integration whenever possible. - -
- - -
- - Creating Keys - -

- For first-time setup, use the bootstrap endpoint to create your initial master key: -

- - - -
-

- Once you have a master key, you can create project keys for your applications: -

- - -
-
- - - {/* Using API Keys */} -
- - Using API Keys - -

- Include your API key in the X-API-Key header - with every request: -

- - - -
- - Environment Variables: Store API keys in environment variables, not - hardcoded in your application. Example:{' '} - BANATIE_API_KEY - -
-
- - {/* Rate Limits */} -
- - Rate Limits - -

- API keys are subject to rate limits to ensure fair usage and system stability. Limits - vary by key type and plan tier: -

- -
Master Key, - Unlimited, - 'N/A', - 'N/A', - ], - [ - Project Key (Free), - 100 requests/hour, - '1 hour rolling', - Yes, - ], - [ - Project Key (Pro), - 1,000 requests/hour, - '1 hour rolling', - Yes, - ], - ]} - /> - -
-

- When you exceed rate limits, the API returns a 429 Too Many Requests status. - Check the response headers for retry timing: -

- - -
- - - {/* Security Best Practices */} -
- - Security Best Practices - - - - Critical Security Guidelines: -
    -
  • Never commit API keys to version control systems (Git, SVN, etc.)
    • -
  • Store keys in environment variables or secret management services
    • -
  • Use project keys in applications, reserve master keys for admin operations
    • -
  • Rotate keys regularly, especially after team member changes
    • -
  • Implement server-side API calls for production applications
    • -
  • Monitor API key usage in your dashboard for suspicious activity
    • -
- - -
-

Key Rotation Example

- -
-
- - - ); -} diff --git a/apps/landing/src/app/docs/images/page.tsx b/apps/landing/src/app/docs/images/page.tsx new file mode 100644 index 0000000..41d4cea --- /dev/null +++ b/apps/landing/src/app/docs/images/page.tsx @@ -0,0 +1,214 @@ +'use client'; + +import { TipBox } from '@/components/docs/shared/TipBox'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { + Hero, + SectionHeader, + InlineCode, + ResponseBlock, +} from '@/components/docs/blocks'; + +const tocItems = [ + { id: 'image-urls', text: 'Image URLs', level: 2 }, + { id: 'uploading-images', text: 'Uploading Images', level: 2 }, + { id: 'listing-images', text: 'Listing & Getting Images', level: 2 }, + { id: 'aliases', text: 'Aliases', level: 2 }, + { id: 'deleting-images', text: 'Deleting Images', level: 2 }, + { id: 'next-steps', text: 'Next Steps', level: 2 }, +]; + +export default function ImagesPage() { + return ( + + + +
+ + Image URLs + +

+ All images are served via CDN with this URL structure: +

+ + + +

+ URLs are permanent, fast, and cached globally. Use them directly in your applications. +

+
+ +
+ + Uploading Images + +

+ Upload your own images for use as brand assets, references, or logos: +

+ + + +

+ Response includes the CDN URL and image details: +

+ + +
+ +
+ + Listing & Getting Images + +

+ List all images in your project: +

+ + + +

+ Get a specific image by ID or alias: +

+ + +
+ +
+ + Aliases + +

+ Assign memorable names to images. Aliases start with @ and make it easy to reference images without remembering UUIDs. +

+ + + +

+ Access images via CDN using their alias: +

+ + + +
+ + Pro Tip: Use aliases for brand assets like @logo, @brand-colors. Reference them in generations without remembering UUIDs. + +
+ +

+ Remove an alias by setting it to null: +

+ + +
+ +
+ + Deleting Images + +

+ Delete an image by ID or alias. This permanently removes the image from storage. +

+ + + +
+ + Deletion is permanent. The image file and all references are removed. + +
+
+ + ); +} diff --git a/apps/landing/src/app/docs/live-urls/page.tsx b/apps/landing/src/app/docs/live-urls/page.tsx new file mode 100644 index 0000000..39e2cc9 --- /dev/null +++ b/apps/landing/src/app/docs/live-urls/page.tsx @@ -0,0 +1,258 @@ +'use client'; + +import { TipBox } from '@/components/docs/shared/TipBox'; +import { Table } from '@/components/docs/shared/Table'; +import { CodeBlock } from '@/components/docs/shared/CodeBlock'; +import { DocPage } from '@/components/docs/layout/DocPage'; +import { + Hero, + SectionHeader, + InlineCode, +} from '@/components/docs/blocks'; + +const tocItems = [ + { id: 'the-concept', text: 'The Concept', level: 2 }, + { id: 'url-format', text: 'URL Format', level: 2 }, + { id: 'try-it', text: 'Try It', level: 2 }, + { id: 'caching-behavior', text: 'Caching Behavior', level: 2 }, + { id: 'scopes', text: 'Scopes', level: 2 }, + { id: 'rate-limits', text: 'Rate Limits', level: 2 }, + { id: 'use-cases', text: 'Use Cases', level: 2 }, + { id: 'next-steps', text: 'Next Steps', level: 2 }, +]; + +export default function LiveUrlsPage() { + return ( + + + +
+ + The Concept + +

+ Put your prompt in a URL. Use it directly in an <img src="..."> tag. +

+

+ First request generates the image. All subsequent requests serve it from cache instantly. +

+
+ +
+ + URL Format + + + + +

+ Query parameters: +

+ +
prompt, + Yes, + 'Text description of the image to generate', + ], + [ + aspectRatio, + No, + 'Image ratio: 1:1, 16:9, 9:16, 3:2 (default: 1:1)', + ], + [ + autoEnhance, + No, + 'Enable prompt enhancement (default: false)', + ], + [ + template, + No, + 'Enhancement template to use', + ], + ]} + /> + + +
+ + Try It + +

+ Open this URL in your browser: +

+ + + +

+ Or use it directly in HTML: +

+ + `} + language="html" + filename="HTML Usage" + /> +
+ +
+ + Caching Behavior + +

+ The response includes an X-Cache-Status header: +

+ +
HIT, + 'Image served from cache', + 'Instant (milliseconds)', + ], + [ + MISS, + 'New image generated', + 'A few seconds', + ], + ]} + /> + +

+ Cache hits are unlimited and don't count toward rate limits. Only new generations (cache MISS) are rate limited. +

+ + +
+ + Scopes + +

+ Scopes organize your live generations. Each scope has its own generation limit. +

+ + + +

+ Scopes are auto-created on first use. You can also pre-configure them via the API to set custom limits. +

+
+ +
+ + Rate Limits + + +
10 new generations/hour, + 'Only applies to cache MISS', + ], + [ + 'Per Scope', + 30 generations, + 'Configurable via API', + ], + [ + 'Cache Hits', + Unlimited, + 'No limits on cached images', + ], + ]} + /> + +
+ + Rate limits protect the service from abuse. For high-volume needs, use the generations API directly. + +
+ + +
+ + Use Cases + + +
    +
  • + • +
    + Dynamic placeholders +

    Generate placeholder images during development that match your design intent.

    +
    +
    • +
  • + • +
    + Personalized content +

    Create unique images based on user data or preferences.

    +
    +
    • +
  • + • +
    + Rapid prototyping +

    Test different visuals without writing backend code.

    +
    +
    • +
  • + • +
    + HTML emails +

    Include dynamic images in email templates with just a URL.

    +
    +
    • +
+
+ + ); +} diff --git a/apps/landing/src/app/docs/page.tsx b/apps/landing/src/app/docs/page.tsx index a1c3e0b..fd5524d 100644 --- a/apps/landing/src/app/docs/page.tsx +++ b/apps/landing/src/app/docs/page.tsx @@ -1,14 +1,5 @@ 'use client'; -/** - * Getting Started Page - Production Documentation - * - * Refactored to use DocPage component for consistent layout - * Layout handles SubsectionNav and Left Sidebar - * DocPage handles Breadcrumb, Article structure, Next Steps, and TOC - * This page provides only the content (Hero + sections) - */ - import { TipBox } from '@/components/docs/shared/TipBox'; import { CodeBlock } from '@/components/docs/shared/CodeBlock'; import { DocPage } from '@/components/docs/layout/DocPage'; @@ -16,14 +7,16 @@ import { Hero, SectionHeader, ResponseBlock, + LinkCard, + LinkCardGrid, } from '@/components/docs/blocks'; const tocItems = [ - { id: 'introduction', text: 'Introduction', level: 2 }, - { id: 'quick-start', text: 'Quick Start', level: 2 }, - { id: 'installation', text: 'Installation', level: 3 }, - { id: 'authentication', text: 'Authentication', level: 3 }, - { id: 'first-request', text: 'Your First Request', level: 2 }, + { id: 'what-is-banatie', text: 'What is Banatie?', level: 2 }, + { id: 'your-first-image', text: 'Your First Image', level: 2 }, + { id: 'production-ready', text: 'Production Ready', level: 2 }, + { id: 'live-urls', text: 'Live URLs', level: 2 }, + { id: 'get-your-api-key', text: 'Get Your API Key', level: 2 }, { id: 'next-steps', text: 'Next Steps', level: 2 }, ]; @@ -36,161 +29,167 @@ export default function GettingStartedPage() { ]} tocItems={tocItems} nextSteps={{ - description: - 'Now that you have generated your first image, explore these resources to build more advanced integrations:', links: [ { - href: '/docs/api/text-to-image', - title: 'API Reference', - description: 'Explore all available endpoints, parameters, and response formats.', + href: '/docs/generation', + title: 'Image Generation', + description: 'Aspect ratios, prompt templates, using references.', accent: 'primary', }, { - href: '/docs/guides/authentication', - title: 'Authentication Guide', - description: 'Learn about API keys, rate limits, and security best practices.', + href: '/docs/images', + title: 'Working with Images', + description: 'Upload your own, organize with aliases.', + accent: 'secondary', + }, + { + href: '/docs/live-urls', + title: 'Live URLs', + description: 'Generate images directly from URL parameters.', + accent: 'primary', + }, + { + href: '/docs/api', + title: 'API Reference', + description: 'Full endpoint documentation.', accent: 'secondary', }, ], }} > + - {/* Hero Section */} - + + 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: +

+ + - {/* Introduction */} -
- - Introduction - -

- Banatie is a developer-first API for AI-powered image generation. Built on Google Gemini - 2.5 Flash and Imagen 4.0, it transforms text prompts and reference images into - production-ready visuals. -

-

- Whether you are building a content creation platform, e-commerce site, or creative tool, - Banatie provides the infrastructure you need to generate high-quality images at scale. -

+

+ That's it. The response contains your image: +

- {/* Compact Tip Box */} - - New to API integration? Start with our{' '} - - code examples - {' '} - to see common use cases in action. - -
- - {/* Quick Start */} -
- - Quick Start - - -
- - Installation - -

- Banatie is a REST API, so you do not need to install any libraries. However, we provide - SDKs for popular languages to make integration easier. -

- - -
- -
- - Authentication - -

- All API requests require an API key. You can create an API key from your dashboard or - using the bootstrap endpoint for initial setup. -

- - {/* Prominent Tip Box for Security Warning */} -
- - Security Best Practice: Keep your API keys secure. - Never commit them to public repositories or expose them in client-side code. Use environment - variables and server-side implementations for production applications. - -
- - -
-
- - {/* First Request */} -
- - Your First Request - -

- Let's generate your first image! This example uses curl, but you can use any HTTP client - or our SDKs. -

- - - -
-

Expected Response:

- -
-
+ /> +

+ 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: +

+ + + +

+ 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 → +

+
+ +
+ + Get Your API Key + +

+ We're currently in early access. API keys are issued personally. +

+ +
+

To request access:

+
    +
  1. Go to banatie.app
    2. +
  2. Enter your email in the signup form
    3. +
  3. We'll send your API key within 24 hours
    4. +
+
+
); } diff --git a/apps/landing/src/components/docs/layout/DocsSidebar.tsx b/apps/landing/src/components/docs/layout/DocsSidebar.tsx index b5e6d6a..f33055d 100644 --- a/apps/landing/src/components/docs/layout/DocsSidebar.tsx +++ b/apps/landing/src/components/docs/layout/DocsSidebar.tsx @@ -41,37 +41,38 @@ const navigationItems: NavItem[] = [ { label: 'Getting Started', href: '/docs', - icon: '🚀', + }, + { + label: 'Image Generation', + href: '/docs/generation', + }, + { + label: 'Working with Images', + href: '/docs/images', + }, + { + label: 'Live URLs', + href: '/docs/live-urls', + }, + { + label: 'Authentication', + href: '/docs/authentication', }, { label: 'API Reference', href: '/docs/api', - icon: '📚', children: [ - { label: 'Text to Image', href: '/docs/api/text-to-image' }, - { label: 'Upload', href: '/docs/api/upload' }, + { label: 'Overview', href: '/docs/api' }, + { label: 'Generations', href: '/docs/api/generations' }, { label: 'Images', href: '/docs/api/images' }, + { label: 'Flows', href: '/docs/api/flows' }, + { label: 'Live Scopes', href: '/docs/api/live-scopes' }, ], }, - { - label: 'Guides', - href: '/docs/guides', - icon: '📖', - children: [ - { label: 'Authentication', href: '/docs/guides/authentication' }, - { label: 'Error Handling', href: '/docs/guides/error-handling' }, - { label: 'Rate Limits', href: '/docs/guides/rate-limits' }, - ], - }, - { - label: 'Examples', - href: '/docs/examples', - icon: '💡', - }, ]; export const DocsSidebar = ({ currentPath }: DocsSidebarProps) => { - const [expandedSections, setExpandedSections] = useState(['API Reference', 'Guides']); + const [expandedSections, setExpandedSections] = useState(['API Reference']); const toggleSection = (label: string) => { setExpandedSections((prev) => @@ -119,10 +120,7 @@ export const DocsSidebar = ({ currentPath }: DocsSidebarProps) => { ${active ? 'bg-purple-500/10 text-white font-medium' : 'text-gray-400 hover:text-white hover:bg-white/5'} `} > - - {item.icon && {item.icon}} - {item.label} - + {item.label} {hasChildren && (