Images API
Upload and manage images for your project.
Upload Image
Upload an image file to your project storage.
POST
/api/v1/images/uploadBase URL: https://api.banatie.app
Form Data
Parameter | Type | Required | Description |
|---|---|---|---|
file | file | Yes | Image file (max 5MB, JPEG/PNG/WebP) |
alias | string | No | Project-scoped alias (@custom-name) |
flowId | string | No | Associate with flow |
meta | string | No | Custom metadata (JSON string) |
Example Request
Request
curl -X POST https://api.banatie.app/api/v1/images/upload \
-H "X-API-Key: YOUR_API_KEY" \
-F "[email protected]" \
-F "alias=@brand-logo"Response
201 Created
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"storageUrl": "https://cdn.banatie.app/my-org/my-project/img/550e8400-e29b-41d4-a716-446655440000",
"alias": "@brand-logo",
"source": "uploaded",
"width": 512,
"height": 512,
"mimeType": "image/png",
"fileSize": 24576,
"createdAt": "2025-01-15T10:30:00Z"
}
}List Images
Retrieve all images in your project with optional filtering.
GET
/api/v1/imagesBase URL: https://api.banatie.app
Query Parameters
Parameter | Type | Description |
|---|---|---|
flowId | string | Filter by flow ID |
source | string | Filter by source: generated, uploaded |
alias | string | Filter by exact alias 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/images?source=uploaded&limit=20" \
-H "X-API-Key: YOUR_API_KEY"Get Image
Retrieve a single image by ID or alias.
GET
/api/v1/images/:id_or_aliasBase URL: https://api.banatie.app
Example Requests
Request
# By UUID
curl https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"
# By alias
curl https://api.banatie.app/api/v1/images/@brand-logo \
-H "X-API-Key: YOUR_API_KEY"Update Image
Update image metadata (focal point and custom metadata).
PUT
/api/v1/images/:id_or_aliasBase URL: https://api.banatie.app
Request Body
Parameter | Type | Description |
|---|---|---|
focalPoint | object | Focal point for cropping {x: 0-1, y: 0-1} |
meta | object | Custom metadata |
Example Request
Request
curl -X PUT https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"focalPoint": {"x": 0.5, "y": 0.3},
"meta": {"category": "hero"}
}'Assign Alias
Assign or remove a project-scoped alias from an image.
PUT
/api/v1/images/:id_or_alias/aliasBase URL: https://api.banatie.app
Request Body
Parameter | Type | Description |
|---|---|---|
alias | string | null | Alias to assign (@name) or null to remove |
Example Requests
Request
# Assign alias
curl -X PUT https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000/alias \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"alias": "@hero-background"}'
# Remove alias
curl -X PUT https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000/alias \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"alias": null}'Delete Image
Permanently delete an image from storage.
DELETE
/api/v1/images/:id_or_aliasBase URL: https://api.banatie.app
Example Request
Request
curl -X DELETE https://api.banatie.app/api/v1/images/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"Deletion is permanent. The image file and all references are removed from storage.
CDN Endpoints
Access images directly via CDN (public, no authentication required):
By Image ID
CDN by ID
GET https://cdn.banatie.app/{org}/{project}/img/{imageId}By Alias
CDN by Alias
GET https://cdn.banatie.app/{org}/{project}/img/@{alias}CDN URLs are public and don't require authentication. They return image bytes directly with appropriate caching headers.