362 lines
12 KiB
TypeScript
362 lines
12 KiB
TypeScript
'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 (
|
|
<DocPage
|
|
breadcrumbItems={[
|
|
{ label: 'Documentation', href: '/docs' },
|
|
{ label: 'API Reference', href: '/docs/api' },
|
|
{ label: 'Images' },
|
|
]}
|
|
tocItems={tocItems}
|
|
nextSteps={{
|
|
links: [
|
|
{
|
|
href: '/docs/images',
|
|
title: 'Working with Images Guide',
|
|
description: 'Concepts and examples for image management.',
|
|
accent: 'primary',
|
|
},
|
|
{
|
|
href: '/docs/api/generations',
|
|
title: 'Generations API',
|
|
description: 'Create AI-generated images.',
|
|
accent: 'secondary',
|
|
},
|
|
],
|
|
}}
|
|
>
|
|
<Hero
|
|
title="Images API"
|
|
subtitle="Upload and manage images for your project."
|
|
/>
|
|
|
|
<section id="upload-image" className="mb-12">
|
|
<SectionHeader level={2} id="upload-image">
|
|
Upload Image
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Upload an image file to your project storage.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="POST"
|
|
endpoint="/api/v1/images/upload"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Form Data</h4>
|
|
<Table
|
|
headers={['Parameter', 'Type', 'Required', 'Description']}
|
|
rows={[
|
|
[
|
|
<InlineCode key="p">file</InlineCode>,
|
|
<span key="t" className="text-cyan-400">file</span>,
|
|
<span key="r" className="text-green-400">Yes</span>,
|
|
'Image file (max 5MB, JPEG/PNG/WebP)',
|
|
],
|
|
[
|
|
<InlineCode key="p">alias</InlineCode>,
|
|
<span key="t" className="text-cyan-400">string</span>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Project-scoped alias (@custom-name)',
|
|
],
|
|
[
|
|
<InlineCode key="p">flowId</InlineCode>,
|
|
<span key="t" className="text-cyan-400">string</span>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Associate with flow',
|
|
],
|
|
[
|
|
<InlineCode key="p">meta</InlineCode>,
|
|
<span key="t" className="text-cyan-400">string</span>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Custom metadata (JSON string)',
|
|
],
|
|
]}
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Example Request</h4>
|
|
<CodeBlock
|
|
code={`curl -X POST https://api.banatie.app/api/v1/images/upload \\
|
|
-H "X-API-Key: YOUR_API_KEY" \\
|
|
-F "file=@your-image.png" \\
|
|
-F "alias=@brand-logo"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Response</h4>
|
|
<ResponseBlock
|
|
status="success"
|
|
statusCode={201}
|
|
statusLabel="201 Created"
|
|
content={`{
|
|
"success": true,
|
|
"data": {
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"storageUrl": "https://cdn.banatie.app/my-org/my-project/img/550e8400-e29b-41d4-a716-446655440000",
|
|
"alias": "@brand-logo",
|
|
"source": "uploaded",
|
|
"width": 512,
|
|
"height": 512,
|
|
"mimeType": "image/png",
|
|
"fileSize": 24576,
|
|
"createdAt": "2025-01-15T10:30:00Z"
|
|
}
|
|
}`}
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="list-images" className="mb-12">
|
|
<SectionHeader level={2} id="list-images">
|
|
List Images
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Retrieve all images in your project with optional filtering.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="GET"
|
|
endpoint="/api/v1/images"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Query Parameters</h4>
|
|
<Table
|
|
headers={['Parameter', 'Type', 'Description']}
|
|
rows={[
|
|
[<InlineCode key="p">flowId</InlineCode>, 'string', 'Filter by flow ID'],
|
|
[<InlineCode key="p">source</InlineCode>, 'string', 'Filter by source: generated, uploaded'],
|
|
[<InlineCode key="p">alias</InlineCode>, 'string', 'Filter by exact alias match'],
|
|
[<InlineCode key="p">limit</InlineCode>, 'number', 'Results per page (default: 20, max: 100)'],
|
|
[<InlineCode key="p">offset</InlineCode>, 'number', 'Number of results to skip'],
|
|
]}
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Example Request</h4>
|
|
<CodeBlock
|
|
code={`curl "https://api.banatie.app/api/v1/images?source=uploaded&limit=20" \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="get-image" className="mb-12">
|
|
<SectionHeader level={2} id="get-image">
|
|
Get Image
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Retrieve a single image by ID or alias.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="GET"
|
|
endpoint="/api/v1/images/:id_or_alias"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Example Requests</h4>
|
|
<CodeBlock
|
|
code={`# By UUID
|
|
curl https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000 \\
|
|
-H "X-API-Key: YOUR_API_KEY"
|
|
|
|
# By alias
|
|
curl https://api.banatie.app/api/v1/images/@brand-logo \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="update-image" className="mb-12">
|
|
<SectionHeader level={2} id="update-image">
|
|
Update Image
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Update image metadata (focal point and custom metadata).
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="PUT"
|
|
endpoint="/api/v1/images/:id_or_alias"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Request Body</h4>
|
|
<Table
|
|
headers={['Parameter', 'Type', 'Description']}
|
|
rows={[
|
|
[<InlineCode key="p">focalPoint</InlineCode>, 'object', 'Focal point for cropping {x: 0-1, y: 0-1}'],
|
|
[<InlineCode key="p">meta</InlineCode>, 'object', 'Custom metadata'],
|
|
]}
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Example Request</h4>
|
|
<CodeBlock
|
|
code={`curl -X PUT https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000 \\
|
|
-H "X-API-Key: YOUR_API_KEY" \\
|
|
-H "Content-Type: application/json" \\
|
|
-d '{
|
|
"focalPoint": {"x": 0.5, "y": 0.3},
|
|
"meta": {"category": "hero"}
|
|
}'`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="assign-alias" className="mb-12">
|
|
<SectionHeader level={2} id="assign-alias">
|
|
Assign Alias
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Assign or remove a project-scoped alias from an image.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="PUT"
|
|
endpoint="/api/v1/images/:id_or_alias/alias"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Request Body</h4>
|
|
<Table
|
|
headers={['Parameter', 'Type', 'Description']}
|
|
rows={[
|
|
[<InlineCode key="p">alias</InlineCode>, 'string | null', 'Alias to assign (@name) or null to remove'],
|
|
]}
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Example Requests</h4>
|
|
<CodeBlock
|
|
code={`# Assign alias
|
|
curl -X PUT https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000/alias \\
|
|
-H "X-API-Key: YOUR_API_KEY" \\
|
|
-H "Content-Type: application/json" \\
|
|
-d '{"alias": "@hero-background"}'
|
|
|
|
# Remove alias
|
|
curl -X PUT https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000/alias \\
|
|
-H "X-API-Key: YOUR_API_KEY" \\
|
|
-H "Content-Type: application/json" \\
|
|
-d '{"alias": null}'`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="delete-image" className="mb-12">
|
|
<SectionHeader level={2} id="delete-image">
|
|
Delete Image
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Permanently delete an image from storage.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="DELETE"
|
|
endpoint="/api/v1/images/:id_or_alias"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Example Request</h4>
|
|
<CodeBlock
|
|
code={`curl -X DELETE https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000 \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<TipBox variant="compact" type="warning">
|
|
Deletion is permanent. The image file and all references are removed from storage.
|
|
</TipBox>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="cdn-endpoints" className="mb-12">
|
|
<SectionHeader level={2} id="cdn-endpoints">
|
|
CDN Endpoints
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Access images directly via CDN (public, no authentication required):
|
|
</p>
|
|
|
|
<div className="space-y-6">
|
|
<div>
|
|
<h4 className="text-sm font-semibold text-white mb-3">By Image ID</h4>
|
|
<CodeBlock
|
|
code={`GET https://cdn.banatie.app/{org}/{project}/img/{imageId}`}
|
|
language="text"
|
|
filename="CDN by ID"
|
|
/>
|
|
</div>
|
|
|
|
<div>
|
|
<h4 className="text-sm font-semibold text-white mb-3">By Alias</h4>
|
|
<CodeBlock
|
|
code={`GET https://cdn.banatie.app/{org}/{project}/img/@{alias}`}
|
|
language="text"
|
|
filename="CDN by Alias"
|
|
/>
|
|
</div>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<TipBox variant="compact" type="info">
|
|
CDN URLs are public and don't require authentication. They return image bytes directly with appropriate caching headers.
|
|
</TipBox>
|
|
</div>
|
|
</section>
|
|
</DocPage>
|
|
);
|
|
}
|