Generations API
Create and manage AI image generations.
Create Generation
Generate a new image from a text prompt.
POST
/api/v1/generationsBase URL: https://api.banatie.app
Request Body
Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Text description of the image to generate |
aspectRatio | string | No | 1:1, 16:9, 9:16, 3:2, 21:9 (default: 1:1) |
referenceImages | string[] | No | Array of image IDs or @aliases to use as references |
flowId | string | No | Associate with existing flow |
alias | string | No | Project-scoped alias (@custom-name) |
autoEnhance | boolean | No | Enable prompt enhancement (default: true) |
meta | object | No | Custom metadata |
Example Request
Request
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"
}'Response
201 Created
{
"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"
}
}List Generations
Retrieve all generations for your project with optional filtering.
GET
/api/v1/generationsBase URL: https://api.banatie.app
Query Parameters
Parameter | Type | Description |
|---|---|---|
flowId | string | Filter by flow ID |
status | string | Filter by status: pending, processing, success, failed |
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/generations?limit=10&status=success" \
-H "X-API-Key: YOUR_API_KEY"Get Generation
Retrieve a single generation by ID.
GET
/api/v1/generations/:idBase URL: https://api.banatie.app
Example Request
Request
curl https://api.banatie.app/api/v1/generations/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"Update Generation
Update generation parameters. Changing prompt or aspectRatio triggers automatic regeneration.
PUT
/api/v1/generations/:idBase URL: https://api.banatie.app
Request Body
Parameter | Type | Description |
|---|---|---|
prompt | string | New prompt (triggers regeneration) |
aspectRatio | string | New aspect ratio (triggers regeneration) |
flowId | string | null | Change flow association |
meta | object | Update custom metadata |
Changing
prompt or aspectRatio triggers a new generation. The image ID and URL remain the same — only the content changes.Regenerate
Create a new image using the exact same parameters. Useful for getting a different result or recovering from failures.
POST
/api/v1/generations/:id/regenerateBase URL: https://api.banatie.app
Example Request
Request
curl -X POST https://api.banatie.app/api/v1/generations/550e8400-e29b-41d4-a716-446655440000/regenerate \
-H "X-API-Key: YOUR_API_KEY"Delete Generation
Delete a generation and its output image. Images with project aliases are preserved.
DELETE
/api/v1/generations/:idBase URL: https://api.banatie.app
Example Request
Request
curl -X DELETE https://api.banatie.app/api/v1/generations/550e8400-e29b-41d4-a716-446655440000 \
-H "X-API-Key: YOUR_API_KEY"Response
200 OK
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000"
}
}