346 lines
12 KiB
TypeScript
346 lines
12 KiB
TypeScript
import type { Metadata } from 'next';
|
|
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 { JsonLd } from '@/components/seo/JsonLd';
|
|
import { createDocsMetadata, DOCS_PAGES } from '@/config/docs-seo';
|
|
import { createBreadcrumbSchema, createTechArticleSchema } from '@/config/docs-schema';
|
|
import {
|
|
Hero,
|
|
SectionHeader,
|
|
InlineCode,
|
|
EndpointCard,
|
|
ResponseBlock,
|
|
} from '@/components/docs/blocks';
|
|
|
|
const PAGE = DOCS_PAGES['api-generations'];
|
|
|
|
export const metadata: Metadata = createDocsMetadata(PAGE);
|
|
|
|
const breadcrumbSchema = createBreadcrumbSchema([
|
|
{ name: 'Home', path: '/' },
|
|
{ name: 'Documentation', path: '/docs/' },
|
|
{ name: 'API Reference', path: '/docs/api/' },
|
|
{ name: 'Generations', path: '/docs/api/generations/' },
|
|
]);
|
|
|
|
const articleSchema = createTechArticleSchema(PAGE);
|
|
|
|
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 (
|
|
<>
|
|
<JsonLd data={breadcrumbSchema} />
|
|
<JsonLd data={articleSchema} />
|
|
<DocPage
|
|
breadcrumbItems={[
|
|
{ label: 'Documentation', href: '/docs/' },
|
|
{ label: 'API Reference', href: '/docs/api/' },
|
|
{ label: 'Generations' },
|
|
]}
|
|
tocItems={tocItems}
|
|
nextSteps={{
|
|
links: [
|
|
{
|
|
href: '/docs/generation/',
|
|
title: 'Image Generation Guide',
|
|
description: 'Concepts and examples for image generation.',
|
|
accent: 'primary',
|
|
},
|
|
{
|
|
href: '/docs/api/images/',
|
|
title: 'Images API',
|
|
description: 'Upload and manage images.',
|
|
accent: 'secondary',
|
|
},
|
|
],
|
|
}}
|
|
>
|
|
<Hero
|
|
title="Generations API"
|
|
subtitle="Create and manage AI image generations."
|
|
/>
|
|
|
|
<section id="create-generation" className="mb-12">
|
|
<SectionHeader level={2} id="create-generation">
|
|
Create Generation
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Generate a new image from a text prompt.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="POST"
|
|
endpoint="/api/v1/generations"
|
|
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', 'Required', 'Description']}
|
|
rows={[
|
|
[
|
|
<InlineCode key="p">prompt</InlineCode>,
|
|
<span key="t" className="text-cyan-400">string</span>,
|
|
<span key="r" className="text-green-400">Yes</span>,
|
|
'Text description of the image to generate',
|
|
],
|
|
[
|
|
<InlineCode key="p">aspectRatio</InlineCode>,
|
|
<span key="t" className="text-cyan-400">string</span>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'1:1, 16:9, 9:16, 3:2, 21:9 (default: 1:1)',
|
|
],
|
|
[
|
|
<InlineCode key="p">referenceImages</InlineCode>,
|
|
<span key="t" className="text-cyan-400">string[]</span>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Array of image IDs or @aliases to use as references',
|
|
],
|
|
[
|
|
<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 existing flow',
|
|
],
|
|
[
|
|
<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">autoEnhance</InlineCode>,
|
|
<span key="t" className="text-cyan-400">boolean</span>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Enable prompt enhancement (default: true)',
|
|
],
|
|
[
|
|
<InlineCode key="p">meta</InlineCode>,
|
|
<span key="t" className="text-cyan-400">object</span>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Custom metadata',
|
|
],
|
|
]}
|
|
/>
|
|
</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/generations \\
|
|
-H "X-API-Key: YOUR_API_KEY" \\
|
|
-H "Content-Type: application/json" \\
|
|
-d '{
|
|
"prompt": "a serene mountain landscape at sunset",
|
|
"aspectRatio": "16:9"
|
|
}'`}
|
|
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",
|
|
"status": "success",
|
|
"prompt": "a serene mountain landscape at sunset",
|
|
"aspectRatio": "16:9",
|
|
"outputImage": {
|
|
"id": "8a3b2c1d-4e5f-6789-abcd-ef0123456789",
|
|
"storageUrl": "https://cdn.banatie.app/my-org/my-project/img/8a3b2c1d-4e5f-6789-abcd-ef0123456789",
|
|
"width": 1792,
|
|
"height": 1008
|
|
},
|
|
"flowId": "770e8400-e29b-41d4-a716-446655440002",
|
|
"createdAt": "2025-01-15T10:30:00Z"
|
|
}
|
|
}`}
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="list-generations" className="mb-12">
|
|
<SectionHeader level={2} id="list-generations">
|
|
List Generations
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Retrieve all generations for your project with optional filtering.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="GET"
|
|
endpoint="/api/v1/generations"
|
|
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">status</InlineCode>, 'string', 'Filter by status: pending, processing, success, failed'],
|
|
[<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/generations?limit=10&status=success" \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="get-generation" className="mb-12">
|
|
<SectionHeader level={2} id="get-generation">
|
|
Get Generation
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Retrieve a single generation by ID.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="GET"
|
|
endpoint="/api/v1/generations/:id"
|
|
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 https://api.banatie.app/api/v1/generations/550e8400-e29b-41d4-a716-446655440000 \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="update-generation" className="mb-12">
|
|
<SectionHeader level={2} id="update-generation">
|
|
Update Generation
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Update generation parameters. Changing prompt or aspectRatio triggers automatic regeneration.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="PUT"
|
|
endpoint="/api/v1/generations/:id"
|
|
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">prompt</InlineCode>, 'string', 'New prompt (triggers regeneration)'],
|
|
[<InlineCode key="p">aspectRatio</InlineCode>, 'string', 'New aspect ratio (triggers regeneration)'],
|
|
[<InlineCode key="p">flowId</InlineCode>, 'string | null', 'Change flow association'],
|
|
[<InlineCode key="p">meta</InlineCode>, 'object', 'Update custom metadata'],
|
|
]}
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<TipBox variant="compact" type="info">
|
|
Changing <InlineCode>prompt</InlineCode> or <InlineCode>aspectRatio</InlineCode> triggers a new generation. The image ID and URL remain the same — only the content changes.
|
|
</TipBox>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="regenerate" className="mb-12">
|
|
<SectionHeader level={2} id="regenerate">
|
|
Regenerate
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Create a new image using the exact same parameters. Useful for getting a different result or recovering from failures.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="POST"
|
|
endpoint="/api/v1/generations/:id/regenerate"
|
|
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 POST https://api.banatie.app/api/v1/generations/550e8400-e29b-41d4-a716-446655440000/regenerate \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="delete-generation" className="mb-12">
|
|
<SectionHeader level={2} id="delete-generation">
|
|
Delete Generation
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Delete a generation and its output image. Images with project aliases are preserved.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="DELETE"
|
|
endpoint="/api/v1/generations/:id"
|
|
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/generations/550e8400-e29b-41d4-a716-446655440000 \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
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={200}
|
|
statusLabel="200 OK"
|
|
content={`{
|
|
"success": true,
|
|
"data": {
|
|
"id": "550e8400-e29b-41d4-a716-446655440000"
|
|
}
|
|
}`}
|
|
/>
|
|
</div>
|
|
</section>
|
|
</DocPage>
|
|
</>
|
|
);
|
|
}
|