420 lines
14 KiB
TypeScript
420 lines
14 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: '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 (
|
|
<DocPage
|
|
breadcrumbItems={[
|
|
{ label: 'Documentation', href: '/docs' },
|
|
{ label: 'API Reference', href: '/docs/api' },
|
|
{ label: 'Live Scopes' },
|
|
]}
|
|
tocItems={tocItems}
|
|
nextSteps={{
|
|
links: [
|
|
{
|
|
href: '/docs/live-urls',
|
|
title: 'Live URLs Guide',
|
|
description: 'Learn about live URL generation.',
|
|
accent: 'primary',
|
|
},
|
|
{
|
|
href: '/docs/api/generations',
|
|
title: 'Generations API',
|
|
description: 'Full control via the generations API.',
|
|
accent: 'secondary',
|
|
},
|
|
],
|
|
}}
|
|
>
|
|
<Hero
|
|
title="Live Scopes API"
|
|
subtitle="Manage scopes for live URL generation."
|
|
/>
|
|
|
|
<section id="overview" className="mb-12">
|
|
<SectionHeader level={2} id="overview">
|
|
Overview
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-4">
|
|
Live scopes organize live URL generations. Each scope has its own generation limit and can be configured independently.
|
|
</p>
|
|
<p className="text-gray-300 leading-relaxed">
|
|
Scopes are auto-created on first use, but you can pre-configure them via this API to set custom limits.
|
|
</p>
|
|
</section>
|
|
|
|
<section id="create-scope" className="mb-12">
|
|
<SectionHeader level={2} id="create-scope">
|
|
Create Scope
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Create a new live scope with custom settings.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="POST"
|
|
endpoint="/api/v1/live/scopes"
|
|
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">slug</InlineCode>,
|
|
<span key="t" className="text-cyan-400">string</span>,
|
|
<span key="r" className="text-green-400">Yes</span>,
|
|
'Unique scope identifier (alphanumeric + hyphens + underscores)',
|
|
],
|
|
[
|
|
<InlineCode key="p">allowNewGenerations</InlineCode>,
|
|
<span key="t" className="text-cyan-400">boolean</span>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Allow new generations (default: true)',
|
|
],
|
|
[
|
|
<InlineCode key="p">newGenerationsLimit</InlineCode>,
|
|
<span key="t" className="text-cyan-400">number</span>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Maximum generations allowed (default: 30)',
|
|
],
|
|
[
|
|
<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/live/scopes \\
|
|
-H "X-API-Key: YOUR_API_KEY" \\
|
|
-H "Content-Type: application/json" \\
|
|
-d '{
|
|
"slug": "hero-section",
|
|
"allowNewGenerations": true,
|
|
"newGenerationsLimit": 50,
|
|
"meta": {"description": "Hero section images"}
|
|
}'`}
|
|
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": "880e8400-e29b-41d4-a716-446655440003",
|
|
"slug": "hero-section",
|
|
"allowNewGenerations": true,
|
|
"newGenerationsLimit": 50,
|
|
"currentGenerations": 0,
|
|
"lastGeneratedAt": null,
|
|
"meta": {"description": "Hero section images"},
|
|
"createdAt": "2025-01-15T10:30:00Z"
|
|
}
|
|
}`}
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="list-scopes" className="mb-12">
|
|
<SectionHeader level={2} id="list-scopes">
|
|
List Scopes
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Retrieve all live scopes for your project.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="GET"
|
|
endpoint="/api/v1/live/scopes"
|
|
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">slug</InlineCode>, 'string', 'Filter by exact slug 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/live/scopes?limit=20" \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="get-scope" className="mb-12">
|
|
<SectionHeader level={2} id="get-scope">
|
|
Get Scope
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Retrieve a single scope with statistics.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="GET"
|
|
endpoint="/api/v1/live/scopes/:slug"
|
|
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/live/scopes/hero-section \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="update-scope" className="mb-12">
|
|
<SectionHeader level={2} id="update-scope">
|
|
Update Scope
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Update scope settings. Changes take effect immediately.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="PUT"
|
|
endpoint="/api/v1/live/scopes/:slug"
|
|
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">allowNewGenerations</InlineCode>, 'boolean', 'Allow/disallow new generations'],
|
|
[<InlineCode key="p">newGenerationsLimit</InlineCode>, 'number', 'Update generation limit'],
|
|
[<InlineCode key="p">meta</InlineCode>, 'object', 'Update 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/live/scopes/hero-section \\
|
|
-H "X-API-Key: YOUR_API_KEY" \\
|
|
-H "Content-Type: application/json" \\
|
|
-d '{
|
|
"allowNewGenerations": false,
|
|
"newGenerationsLimit": 100
|
|
}'`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="regenerate-scope" className="mb-12">
|
|
<SectionHeader level={2} id="regenerate-scope">
|
|
Regenerate Scope
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Regenerate images in a scope. Can regenerate a specific image or all images.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="POST"
|
|
endpoint="/api/v1/live/scopes/:slug/regenerate"
|
|
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">imageId</InlineCode>, 'string', 'Specific image to regenerate (omit for all)'],
|
|
]}
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Example Requests</h4>
|
|
<CodeBlock
|
|
code={`# Regenerate specific image
|
|
curl -X POST https://api.banatie.app/api/v1/live/scopes/hero-section/regenerate \\
|
|
-H "X-API-Key: YOUR_API_KEY" \\
|
|
-H "Content-Type: application/json" \\
|
|
-d '{"imageId": "550e8400-e29b-41d4-a716-446655440000"}'
|
|
|
|
# Regenerate all images in scope
|
|
curl -X POST https://api.banatie.app/api/v1/live/scopes/hero-section/regenerate \\
|
|
-H "X-API-Key: YOUR_API_KEY" \\
|
|
-H "Content-Type: application/json" \\
|
|
-d '{}'`}
|
|
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": {
|
|
"regenerated": 3,
|
|
"images": [...]
|
|
}
|
|
}`}
|
|
/>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="delete-scope" className="mb-12">
|
|
<SectionHeader level={2} id="delete-scope">
|
|
Delete Scope
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Delete a scope and all its cached images.
|
|
</p>
|
|
|
|
<EndpointCard
|
|
method="DELETE"
|
|
endpoint="/api/v1/live/scopes/:slug"
|
|
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/live/scopes/hero-section \\
|
|
-H "X-API-Key: YOUR_API_KEY"`}
|
|
language="bash"
|
|
filename="Request"
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<TipBox variant="compact" type="warning">
|
|
Deleting a scope permanently removes all cached images in it. This cannot be undone.
|
|
</TipBox>
|
|
</div>
|
|
</section>
|
|
|
|
<section id="cdn-live-endpoint" className="mb-12">
|
|
<SectionHeader level={2} id="cdn-live-endpoint">
|
|
CDN Live Endpoint
|
|
</SectionHeader>
|
|
<p className="text-gray-300 leading-relaxed mb-6">
|
|
Public endpoint for live URL generation (no authentication required):
|
|
</p>
|
|
|
|
<CodeBlock
|
|
code={`GET https://cdn.banatie.app/{org}/{project}/live/{scope}?prompt=...`}
|
|
language="text"
|
|
filename="Live URL Format"
|
|
/>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Query Parameters</h4>
|
|
<Table
|
|
headers={['Parameter', 'Required', 'Description']}
|
|
rows={[
|
|
[
|
|
<InlineCode key="p">prompt</InlineCode>,
|
|
<span key="r" className="text-green-400">Yes</span>,
|
|
'Text description of the image to generate',
|
|
],
|
|
[
|
|
<InlineCode key="p">aspectRatio</InlineCode>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Image ratio (default: 1:1)',
|
|
],
|
|
[
|
|
<InlineCode key="p">autoEnhance</InlineCode>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Enable prompt enhancement',
|
|
],
|
|
[
|
|
<InlineCode key="p">template</InlineCode>,
|
|
<span key="r" className="text-gray-500">No</span>,
|
|
'Enhancement template to use',
|
|
],
|
|
]}
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Example</h4>
|
|
<CodeBlock
|
|
code={`https://cdn.banatie.app/my-org/my-project/live/hero-section?prompt=mountain+landscape&aspectRatio=16:9`}
|
|
language="text"
|
|
filename="Live URL Example"
|
|
/>
|
|
</div>
|
|
|
|
<div className="mt-6">
|
|
<h4 className="text-sm font-semibold text-white mb-4">Response Headers</h4>
|
|
<Table
|
|
headers={['Header', 'Description']}
|
|
rows={[
|
|
[<InlineCode key="h">X-Cache-Status</InlineCode>, 'HIT (cached) or MISS (generated)'],
|
|
[<InlineCode key="h">X-Scope</InlineCode>, 'Scope identifier'],
|
|
[<InlineCode key="h">X-Image-Id</InlineCode>, 'Image UUID'],
|
|
[<InlineCode key="h">X-RateLimit-Remaining</InlineCode>, 'Remaining IP rate limit (on MISS)'],
|
|
]}
|
|
/>
|
|
</div>
|
|
</section>
|
|
</DocPage>
|
|
);
|
|
}
|