331 lines
11 KiB
TypeScript
331 lines
11 KiB
TypeScript
'use client';
|
|
|
|
/**
|
|
* API Reference: Image Management
|
|
*
|
|
* Based on docs/api/images-upload.md (CRUD 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,
|
|
EndpointCard,
|
|
} from '@/components/docs/blocks';
|
|
|
|
const tocItems = [
|
|
{ id: 'overview', text: 'Overview', level: 2 },
|
|
{ id: 'list-images', text: 'List Images', level: 2 },
|
|
{ id: 'get-image', text: 'Get Image', level: 2 },
|
|
{ id: 'update-metadata', text: 'Update Metadata', level: 2 },
|
|
{ id: 'assign-alias', text: 'Assign Alias', level: 2 },
|
|
{ id: 'delete-image', text: 'Delete Image', level: 2 },
|
|
{ id: 'response-fields', text: 'Response Fields', level: 2 },
|
|
{ id: 'next-steps', text: 'Next Steps', level: 2 },
|
|
];
|
|
|
|
const listQueryParams = [
|
|
{ name: 'flowId', type: 'string', default: '-', description: 'Filter by flow UUID' },
|
|
{ name: 'source', type: 'string', default: '-', description: 'Filter by source: generated, uploaded' },
|
|
{ name: 'alias', type: 'string', default: '-', description: 'Filter by exact alias match' },
|
|
{ name: 'limit', type: 'number', default: '20', description: 'Results per page (max: 100)' },
|
|
{ name: 'offset', type: 'number', default: '0', description: 'Pagination offset' },
|
|
{ name: 'includeDeleted', type: 'boolean', default: 'false', description: 'Include soft-deleted records' },
|
|
];
|
|
|
|
const responseFields = [
|
|
['id', 'string', 'Image UUID (same as filename in storage)'],
|
|
['projectId', 'string', 'Project UUID'],
|
|
['flowId', 'string', 'Associated flow UUID (null if none)'],
|
|
['storageUrl', 'string', 'CDN URL for direct access'],
|
|
['mimeType', 'string', 'Image MIME type'],
|
|
['fileSize', 'number', 'File size in bytes'],
|
|
['width', 'number', 'Image width in pixels'],
|
|
['height', 'number', 'Image height in pixels'],
|
|
['source', 'string', '"generated" or "uploaded"'],
|
|
['alias', 'string', 'Project-scoped alias (null if none)'],
|
|
['focalPoint', 'object', '{ x, y } coordinates (0.0-1.0)'],
|
|
['meta', 'object', 'Custom metadata'],
|
|
['createdAt', 'string', 'ISO timestamp'],
|
|
['updatedAt', 'string', 'ISO timestamp'],
|
|
];
|
|
|
|
export default function ImageManagementPage() {
|
|
return (
|
|
<DocPage
|
|
breadcrumbItems={[
|
|
{ label: 'Documentation', href: '/docs' },
|
|
{ label: 'API Reference', href: '/docs/api' },
|
|
{ label: 'Image Management' },
|
|
]}
|
|
tocItems={tocItems}
|
|
nextSteps={{
|
|
links: [
|
|
{
|
|
href: '/docs/api/live',
|
|
title: 'Live URLs',
|
|
description: 'Learn about CDN access and live URL generation.',
|
|
accent: 'primary',
|
|
},
|
|
{
|
|
href: '/docs/api/advanced',
|
|
title: 'Advanced Generation',
|
|
description: 'Use aliases and references in generation workflows.',
|
|
accent: 'secondary',
|
|
},
|
|
],
|
|
}}
|
|
>
|
|
{/* Hero Section */}
|
|
<Hero
|
|
title="Image Management"
|
|
subtitle="List, retrieve, update, and delete images in your project."
|
|
/>
|
|
|
|
{/* Overview */}
|
|
<section id="overview" className="mb-12">
|
|
<SectionHeader level={2} id="overview">
|
|
Overview
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-4">
|
|
The Image Management API provides CRUD operations for images in your project.
|
|
Access images by UUID or alias, update metadata, and manage aliases for easy reference.
|
|
</p>
|
|
<TipBox variant="compact" type="info">
|
|
<strong>Tip:</strong> Use aliases like <InlineCode>@hero</InlineCode> for human-readable
|
|
references instead of UUIDs.
|
|
</TipBox>
|
|
</section>
|
|
|
|
{/* List Images */}
|
|
<section id="list-images" className="mb-12">
|
|
<SectionHeader level={2} id="list-images">
|
|
List Images
|
|
</SectionHeader>
|
|
<EndpointCard
|
|
method="GET"
|
|
endpoint="/api/v1/images"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
|
|
<SectionHeader level={3} id="list-params" className="mt-6 mb-4">
|
|
Query Parameters
|
|
</SectionHeader>
|
|
<Table
|
|
headers={['Parameter', 'Type', 'Default', 'Description']}
|
|
rows={listQueryParams.map((param) => [
|
|
<InlineCode key="name">{param.name}</InlineCode>,
|
|
<span key="type" className="text-cyan-400">{param.type}</span>,
|
|
param.default === '-' ? <span className="text-gray-500">-</span> : <InlineCode key="default">{param.default}</InlineCode>,
|
|
param.description,
|
|
])}
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<CodeBlock
|
|
code={`{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": "7c4ccf47-41ce-4718-afbc-8c553b2c631a",
|
|
"storageUrl": "https://cdn.banatie.app/default/my-project/img/7c4ccf47-...",
|
|
"source": "uploaded",
|
|
"alias": "@brand-logo",
|
|
"width": 512,
|
|
"height": 512,
|
|
"createdAt": "2025-11-28T10:00:00.000Z"
|
|
}
|
|
],
|
|
"pagination": {
|
|
"limit": 20,
|
|
"offset": 0,
|
|
"total": 25,
|
|
"hasMore": true
|
|
}
|
|
}`}
|
|
language="json"
|
|
filename="Response"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
{/* Get Image */}
|
|
<section id="get-image" className="mb-12">
|
|
<SectionHeader level={2} id="get-image">
|
|
Get Image
|
|
</SectionHeader>
|
|
<EndpointCard
|
|
method="GET"
|
|
endpoint="/api/v1/images/:id_or_alias"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
<p className="text-gray-300 leading-relaxed mt-4 mb-4">
|
|
Retrieve a single image by UUID or alias.
|
|
</p>
|
|
|
|
<CodeBlock
|
|
code={`# By UUID
|
|
GET /api/v1/images/7c4ccf47-41ce-4718-afbc-8c553b2c631a
|
|
|
|
# By project alias
|
|
GET /api/v1/images/@brand-logo
|
|
|
|
# By technical alias (requires flowId)
|
|
GET /api/v1/images/@last?flowId=flow-123
|
|
|
|
# By flow alias
|
|
GET /api/v1/images/@hero?flowId=flow-123`}
|
|
language="bash"
|
|
filename="Examples"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<TipBox variant="compact" type="info">
|
|
<strong>Alias Resolution:</strong> When using aliases with <InlineCode>flowId</InlineCode>,
|
|
the system checks flow aliases first, then falls back to project aliases.
|
|
</TipBox>
|
|
</div>
|
|
</section>
|
|
|
|
{/* Update Metadata */}
|
|
<section id="update-metadata" className="mb-12">
|
|
<SectionHeader level={2} id="update-metadata">
|
|
Update Metadata
|
|
</SectionHeader>
|
|
<EndpointCard
|
|
method="PUT"
|
|
endpoint="/api/v1/images/:id_or_alias"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
<p className="text-gray-300 leading-relaxed mt-4 mb-4">
|
|
Update image metadata including focal point and custom data.
|
|
</p>
|
|
|
|
<CodeBlock
|
|
code={`{
|
|
"focalPoint": { "x": 0.5, "y": 0.3 },
|
|
"meta": {
|
|
"description": "Updated brand logo",
|
|
"tags": ["logo", "brand", "2025"]
|
|
}
|
|
}`}
|
|
language="json"
|
|
filename="Request Body"
|
|
/>
|
|
|
|
<p className="text-gray-400 text-sm mt-4">
|
|
<strong>Note:</strong> Alias assignment has its own dedicated endpoint.
|
|
</p>
|
|
</section>
|
|
|
|
{/* Assign Alias */}
|
|
<section id="assign-alias" className="mb-12">
|
|
<SectionHeader level={2} id="assign-alias">
|
|
Assign Alias
|
|
</SectionHeader>
|
|
<EndpointCard
|
|
method="PUT"
|
|
endpoint="/api/v1/images/:id_or_alias/alias"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
<p className="text-gray-300 leading-relaxed mt-4 mb-4">
|
|
Assign or remove a project-scoped alias from an image.
|
|
</p>
|
|
|
|
<CodeBlock
|
|
code={`// Assign alias
|
|
{ "alias": "@new-logo" }
|
|
|
|
// Remove alias
|
|
{ "alias": null }`}
|
|
language="json"
|
|
filename="Request Body"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<TipBox variant="compact" type="warning">
|
|
<strong>Override Behavior:</strong> If another image has the alias, it loses the alias.
|
|
The target image gets the alias. The old image is preserved, just unlinked.
|
|
</TipBox>
|
|
</div>
|
|
</section>
|
|
|
|
{/* Delete Image */}
|
|
<section id="delete-image" className="mb-12">
|
|
<SectionHeader level={2} id="delete-image">
|
|
Delete Image
|
|
</SectionHeader>
|
|
<EndpointCard
|
|
method="DELETE"
|
|
endpoint="/api/v1/images/:id_or_alias"
|
|
baseUrl="https://api.banatie.app"
|
|
/>
|
|
<p className="text-gray-300 leading-relaxed mt-4 mb-4">
|
|
Permanently delete an image and its storage file.
|
|
</p>
|
|
|
|
<CodeBlock
|
|
code={`{
|
|
"success": true,
|
|
"message": "Image deleted"
|
|
}`}
|
|
language="json"
|
|
filename="Response"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<TipBox variant="prominent" type="warning">
|
|
<strong>Warning:</strong> This action is irreversible. The image record and storage file
|
|
are permanently deleted. Related generations will have their <InlineCode>outputImageId</InlineCode> set to null.
|
|
</TipBox>
|
|
</div>
|
|
</section>
|
|
|
|
{/* Response Fields */}
|
|
<section id="response-fields" className="mb-12">
|
|
<SectionHeader level={2} id="response-fields" className="mb-6">
|
|
Response Fields
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Complete list of fields returned in image responses:
|
|
</p>
|
|
|
|
<Table
|
|
headers={['Field', 'Type', 'Description']}
|
|
rows={responseFields.map(([field, type, description]) => [
|
|
<InlineCode key="field">{field}</InlineCode>,
|
|
<span key="type" className="text-cyan-400">{type}</span>,
|
|
description,
|
|
])}
|
|
/>
|
|
|
|
<SectionHeader level={3} id="accessing-images" className="mt-8 mb-4">
|
|
Accessing Images
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-4">
|
|
Use <InlineCode>storageUrl</InlineCode> for direct CDN access:
|
|
</p>
|
|
|
|
<CodeBlock
|
|
code={`<!-- Direct access via UUID (fastest, cached) -->
|
|
<img src="https://cdn.banatie.app/default/my-project/img/7c4ccf47-..." />
|
|
|
|
<!-- Access via alias (requires API resolution) -->
|
|
<img src="https://cdn.banatie.app/default/my-project/img/@brand-logo" />`}
|
|
language="html"
|
|
filename="Usage Examples"
|
|
/>
|
|
|
|
<TipBox variant="compact" type="info">
|
|
<strong>Performance:</strong> UUID URLs are served directly from CDN.
|
|
Alias URLs require API resolution but enable dynamic reassignment.
|
|
</TipBox>
|
|
</section>
|
|
</DocPage>
|
|
);
|
|
}
|