# Images
AI image generation
## GET /v1/images
> Fetch list of generated images
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Images","description":"AI image generation"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/images":{"get":{"summary":"Fetch list of generated images","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","maximum":50},"description":"Maximum number of images to return (max 50, default 20)"}],"responses":{"200":{"description":"A list of generated images","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","required":["id","url"],"properties":{"id":{"type":"string"},"url":{"type":"string"}}}}}}}},"tags":["Images"]}}}}
```
## POST /v1/images
> Create an image
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Images","description":"AI image generation"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/images":{"post":{"summary":"Create an image","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","description":"The model to use for image generation. Use the `/v1/meta/image_models` endpoint to get the full list.\nOpenAI models use the `size` setting. Replicate/Google models use the `aspect_ratio` setting.\n"},"prompt":{"type":"string","maxLength":1000,"description":"The prompt to use for image generation"},"settings":{"type":"object","description":"Image generation settings. Use `size` for OpenAI models, `aspect_ratio` for Replicate/Google models.","properties":{"size":{"type":"string","enum":["1024x1024","1536x1024","1024x1536"],"default":"1536x1024","description":"Pixel size of the image. Valid for OpenAI models (gpt-image-1, gpt-image-1.5, gpt-image-2) only.\n1024x1024 (square), 1536x1024 (landscape), 1024x1536 (portrait).\n"},"aspect_ratio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4","3:2","2:3","5:4","4:5","21:9","9:21"],"default":"16:9","description":"Aspect ratio of the image. Valid for Replicate and Google models.\nNot all ratios are supported by all models. Common options: 16:9 (landscape), 9:16 (portrait/stories), 1:1 (square), 4:3 (standard), 3:2 (classic).\n"},"resolution":{"type":"string","enum":["1K","2K","4K"],"description":"Output resolution. Only valid for `replicate:nano-banana-pro`.\n1K: Fast, good for previews. 2K: Balanced (default). 4K: Highest quality, slower.\n"}}}}}}}},"responses":{"200":{"description":"Successfully generated image","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}}}}},"tags":["Images"]}}}}
```
## Start bulk image generation
> Generate featured images for multiple articles at once. Returns a request ID to poll for status.\
> Requires Power plan or higher.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Images","description":"AI image generation"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/images/bulk":{"post":{"summary":"Start bulk image generation","description":"Generate featured images for multiple articles at once. Returns a request ID to poll for status.\nRequires Power plan or higher.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["article_ids"],"properties":{"article_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50,"description":"Array of article IDs to generate images for"},"model":{"type":"string","default":"gpt-image-1","description":"Image generation model to use"},"use_brand_colors":{"type":"boolean","default":false,"description":"Whether to incorporate brand colors into images"},"prompt_template":{"type":"string","description":"Optional custom prompt template"}}}}}},"responses":{"202":{"description":"Bulk image generation started","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"total_articles":{"type":"number"},"status":{"type":"string","enum":["queued"]}}}}}}},"tags":["Images"]}}}}
```
## Get bulk image generation status
> Poll for the status of a bulk image generation request.
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Images","description":"AI image generation"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/images/bulk/{requestId}":{"get":{"summary":"Get bulk image generation status","description":"Poll for the status of a bulk image generation request.","parameters":[{"in":"path","name":"requestId","required":true,"schema":{"type":"string","format":"uuid"},"description":"The bulk request ID"}],"responses":{"200":{"description":"Bulk image status","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string"},"status":{"type":"string","enum":["waiting","processing","completed","failed","canceled"]},"total_articles":{"type":"number"},"completed_articles":{"type":"number"},"failed_articles":{"type":"number"},"model":{"type":"string"},"articles":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string"},"image_url":{"type":"string","nullable":true},"error":{"type":"string","nullable":true}}}}}}}}}},"tags":["Images"]}}}}
```
## DELETE /v1/images/bulk/{requestId}
> Cancel bulk image generation
```json
{"openapi":"3.1.0","info":{"title":"Cuppa API","version":"1.0.0"},"tags":[{"name":"Images","description":"AI image generation"}],"servers":[{"url":"https://api.cuppa.ai"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-KEY"}}},"paths":{"/v1/images/bulk/{requestId}":{"delete":{"summary":"Cancel bulk image generation","parameters":[{"in":"path","name":"requestId","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}},"tags":["Images"]}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://learn.cuppa.ai/rest-api/images.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.