usulpro
/
banatie-service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
banatie-service/docs/api/live-url.md

381 lines
8.7 KiB
Markdown
Raw Blame History

# Live URL & CDN API
Public CDN endpoints for image serving and live URL generation. For authenticated API, see [image-generation.md](image-generation.md).
---
## CDN Image Serving
```
GET /cdn/:orgSlug/:projectSlug/img/:filenameOrAlias
```
**Authentication:** None - Public endpoint
Serve images by filename or project-scoped alias.
**Path Parameters:**
| Parameter | Description |
|-----------|-------------|
| `orgSlug` | Organization identifier |
| `projectSlug` | Project identifier |
| `filenameOrAlias` | Filename or `@alias` |
**Examples:**
```
# By filename
GET /cdn/acme/website/img/hero-background.jpg
# By alias
GET /cdn/acme/website/img/@hero
```
**Response:** Raw image bytes (not JSON)
**Response Headers:**
| Header | Value |
|--------|-------|
| `Content-Type` | `image/jpeg`, `image/png`, etc. |
| `Content-Length` | File size in bytes |
| `Cache-Control` | `public, max-age=31536000` (1 year) |
| `X-Image-Id` | Image UUID |
---
## Live URL Generation
```
GET /cdn/:orgSlug/:projectSlug/live/:scope
```
**Authentication:** None - Public endpoint
Generate images on-demand via URL parameters with automatic caching.
**Path Parameters:**
| Parameter | Description |
|-----------|-------------|
| `orgSlug` | Organization identifier |
| `projectSlug` | Project identifier |
| `scope` | Scope identifier (alphanumeric, hyphens, underscores) |
**Query Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `prompt` | string | Yes | - | Image description |
| `aspectRatio` | string | No | `"1:1"` | Aspect ratio |
| `autoEnhance` | boolean | No | `true` | Enable prompt enhancement |
| `template` | string | No | `"general"` | Enhancement template |
**Example:**
```
GET /cdn/acme/website/live/hero-section?prompt=mountain+landscape&aspectRatio=16:9
```
**Response:** Raw image bytes
### Cache Behavior
**Cache HIT** - Image exists in cache:
- Returns instantly
- No rate limit check
- Headers include `X-Cache-Status: HIT`
**Cache MISS** - New generation:
- Generates image using AI
- Stores in cache
- Counts toward rate limit
- Headers include `X-Cache-Status: MISS`
**Cache Key:** Computed from `projectId + scope + prompt + aspectRatio + autoEnhance + template`
### Response Headers
**Cache HIT:**
| Header | Value |
|--------|-------|
| `Content-Type` | `image/jpeg` |
| `Cache-Control` | `public, max-age=31536000` |
| `X-Cache-Status` | `HIT` |
| `X-Scope` | Scope identifier |
| `X-Image-Id` | Image UUID |
**Cache MISS:**
| Header | Value |
|--------|-------|
| `Content-Type` | `image/jpeg` |
| `Cache-Control` | `public, max-age=31536000` |
| `X-Cache-Status` | `MISS` |
| `X-Scope` | Scope identifier |
| `X-Generation-Id` | Generation UUID |
| `X-Image-Id` | Image UUID |
| `X-RateLimit-Limit` | `10` |
| `X-RateLimit-Remaining` | Remaining requests |
| `X-RateLimit-Reset` | Seconds until reset |
---
## IP Rate Limiting
Live URLs are rate limited by IP address:
| Limit | Value |
|-------|-------|
| New generations | 10 per hour per IP |
| Cache hits | Unlimited |
**Note:** Only cache MISS (new generations) count toward the limit. Cache HIT requests are not limited.
Rate limit headers are included on MISS responses:
- `X-RateLimit-Limit`: Maximum requests (10)
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Seconds until reset
---
## Scope Management
Scopes organize live URL generation budgets. All scope endpoints require Project Key authentication.
### Create Scope
```
POST /api/v1/live/scopes
```
**Request Body:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `slug` | string | Yes | - | Unique identifier |
| `allowNewGenerations` | boolean | No | `true` | Allow new generations |
| `newGenerationsLimit` | number | No | `30` | Max generations in scope |
| `meta` | object | No | `{}` | Custom metadata |
**Example:**
```json
{
"slug": "hero-section",
"allowNewGenerations": true,
"newGenerationsLimit": 50,
"meta": { "description": "Hero section images" }
}
```
**Response:** `201 Created`
```json
{
"success": true,
"data": {
"id": "scope-123",
"projectId": "project-456",
"slug": "hero-section",
"allowNewGenerations": true,
"newGenerationsLimit": 50,
"currentGenerations": 0,
"lastGeneratedAt": null,
"meta": { "description": "Hero section images" },
"createdAt": "2025-11-28T10:00:00.000Z"
}
}
```
### Lazy Scope Creation
Scopes are auto-created on first live URL request if `project.allowNewLiveScopes = true`:
```
GET /cdn/acme/website/live/new-scope?prompt=...
// Creates "new-scope" with default settings
```
### List Scopes
```
GET /api/v1/live/scopes
```
**Query Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `slug` | string | - | Filter by exact slug |
| `limit` | number | `20` | Results per page (max: 100) |
| `offset` | number | `0` | Pagination offset |
**Response:**
```json
{
"success": true,
"data": [
{
"id": "scope-123",
"slug": "hero-section",
"allowNewGenerations": true,
"newGenerationsLimit": 50,
"currentGenerations": 12,
"lastGeneratedAt": "2025-11-28T09:30:00.000Z"
}
],
"pagination": { "limit": 20, "offset": 0, "total": 3, "hasMore": false }
}
```
### Get Scope
```
GET /api/v1/live/scopes/:slug
```
Returns scope with statistics (currentGenerations, lastGeneratedAt).
### Update Scope
```
PUT /api/v1/live/scopes/:slug
```
```json
{
"allowNewGenerations": false,
"newGenerationsLimit": 100,
"meta": { "description": "Updated" }
}
```
Changes take effect immediately for new requests.
### Regenerate Scope Images
```
POST /api/v1/live/scopes/:slug/regenerate
```
**Request Body:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `imageId` | string | Specific image UUID (optional) |
**Behavior:**
- If `imageId` provided: Regenerate only that image
- If `imageId` omitted: Regenerate all images in scope
Images are regenerated with exact same parameters. IDs and URLs are preserved.
### Delete Scope
```
DELETE /api/v1/live/scopes/:slug
```
**Cascade Behavior:**
- Scope record is **hard deleted**
- All images in scope are **hard deleted** (with MinIO cleanup)
- Follows alias protection rules (aliased images may be kept)
> **Warning:** This permanently deletes all cached images in the scope.
---
## Scope Settings
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `slug` | string | - | Unique identifier within project |
| `allowNewGenerations` | boolean | `true` | Whether new generations are allowed |
| `newGenerationsLimit` | number | `30` | Maximum generations in scope |
When `allowNewGenerations: false`:
- Cache HITs still work
- New prompts return 403 error
When `newGenerationsLimit` reached:
- Cache HITs still work
- New prompts return 429 error
---
## Authenticated Live Endpoint
```
GET /api/v1/live?prompt=...
```
**Authentication:** Project Key required
Alternative to CDN endpoint with prompt caching by hash.
**Query Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | Image description |
**Cache Behavior:**
- Cache key: SHA-256 hash of prompt
- Cache stored in `prompt_url_cache` table
- Tracks hit count and last access
**Response Headers:**
- `X-Cache-Status`: `HIT` or `MISS`
- `X-Cache-Hit-Count`: Number of cache hits (on HIT)
---
## Error Codes
| HTTP Status | Code | Description |
|-------------|------|-------------|
| 400 | `SCOPE_INVALID_FORMAT` | Invalid scope slug format |
| 403 | `SCOPE_CREATION_DISABLED` | New scope creation not allowed |
| 404 | `ORG_NOT_FOUND` | Organization not found |
| 404 | `PROJECT_NOT_FOUND` | Project not found |
| 404 | `SCOPE_NOT_FOUND` | Scope does not exist |
| 409 | `SCOPE_ALREADY_EXISTS` | Scope slug already in use |
| 429 | `IP_RATE_LIMIT_EXCEEDED` | IP rate limit (10/hour) exceeded |
| 429 | `SCOPE_GENERATION_LIMIT_EXCEEDED` | Scope limit reached |
---
## Use Cases
### Dynamic Hero Images
```html
<img src="/cdn/acme/website/live/hero?prompt=professional+office+workspace&aspectRatio=16:9" />
```
First load generates, subsequent loads are cached.
### Product Placeholders
```html
<img src="/cdn/acme/store/live/products?prompt=product+placeholder+gray+box&aspectRatio=1:1" />
```
### Blog Post Images
```html
<img src="/cdn/acme/blog/live/posts?prompt=abstract+technology+background&aspectRatio=16:9&template=illustration" />
```
---
## See Also
- [Basic Generation](image-generation.md) - API-based generation
- [Advanced Generation](image-generation-advanced.md) - References, aliases, flows
- [Image Upload](images-upload.md) - Upload and manage images
Reference in New Issue View Git Blame Copy Permalink