Live Scopes API
Manage scopes for live URL generation.
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.
POST
/api/v1/live/scopesBase URL: https://api.banatie.app
Request Body
Parameter | Type | Required | Description |
|---|---|---|---|
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
Request
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"}
}'Response
201 Created
{
"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"
}
}List Scopes
Retrieve all live scopes for your project.
GET
/api/v1/live/scopesBase URL: https://api.banatie.app
Query Parameters
Parameter | Type | Description |
|---|---|---|
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
Request
curl "https://api.banatie.app/api/v1/live/scopes?limit=20" \
-H "X-API-Key: YOUR_API_KEY"Get Scope
Retrieve a single scope with statistics.
GET
/api/v1/live/scopes/:slugBase URL: https://api.banatie.app
Example Request
Request
curl https://api.banatie.app/api/v1/live/scopes/hero-section \
-H "X-API-Key: YOUR_API_KEY"Update Scope
Update scope settings. Changes take effect immediately.
PUT
/api/v1/live/scopes/:slugBase URL: https://api.banatie.app
Request Body
Parameter | Type | Description |
|---|---|---|
allowNewGenerations | boolean | Allow/disallow new generations |
newGenerationsLimit | number | Update generation limit |
meta | object | Update custom metadata |
Example Request
Request
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
}'Regenerate Scope
Regenerate images in a scope. Can regenerate a specific image or all images.
POST
/api/v1/live/scopes/:slug/regenerateBase URL: https://api.banatie.app
Request Body
Parameter | Type | Description |
|---|---|---|
imageId | string | Specific image to regenerate (omit for all) |
Example Requests
Request
# 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 '{}'Response
200 OK
{
"success": true,
"data": {
"regenerated": 3,
"images": [...]
}
}Delete Scope
Delete a scope and all its cached images.
DELETE
/api/v1/live/scopes/:slugBase URL: https://api.banatie.app
Example Request
Request
curl -X DELETE https://api.banatie.app/api/v1/live/scopes/hero-section \
-H "X-API-Key: YOUR_API_KEY"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):
Live URL Format
GET https://cdn.banatie.app/{org}/{project}/live/{scope}?prompt=...Query Parameters
Parameter | Required | Description |
|---|---|---|
prompt | Yes | Text description of the image to generate |
aspectRatio | No | Image ratio (default: 16:9) |
autoEnhance | No | Enable prompt enhancement |
template | No | Enhancement template to use |
Example
Live URL Example
https://cdn.banatie.app/my-org/my-project/live/hero-section?prompt=mountain+landscape&aspectRatio=16:9Response Headers
Header | Description |
|---|---|
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) |