> For the complete documentation index, see [llms.txt](https://docs.qolaba.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qolaba.ai/api-platform/image-generation/try-image-generation.md).

# Try Image Generation

Test the image generation API interactively. Select a model, configure parameters, and generate images.

## Generate images

> Generate images from text prompts. See the model-specific guides below for detailed usage.

```json
{"openapi":"3.0.3","info":{"title":"Qolaba Image Generation API","version":"1.0.0"},"tags":[{"name":"Image Generation","description":"Generate images from text prompts"}],"servers":[{"url":"https://api.platform.qolaba.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key passed as a Bearer token.\nGenerate your key at [platform.qolaba.ai](https://platform.qolaba.ai).\nExample: `Authorization: Bearer sk-xxxxxxxxxxxx`\n"}},"schemas":{"ImageGenerateRequest":{"type":"object","required":["model","prompt"],"properties":{"model":{"type":"string","description":"Image model ID","enum":["vertex/nano-banana-flash","vertex/nano-banana-pro","vertex/imagen-4","vertex/imagen-4-fast","vertex/imagen-4-ultra"]},"prompt":{"type":"string","maxLength":4000,"description":"Text description of the image to generate"},"mode":{"type":"string","enum":["sync","async"],"default":"sync","description":"sync returns images directly; async returns a task_id to poll"},"negative_prompt":{"type":"string","maxLength":2000,"description":"What to avoid in the generated image"},"aspect_ratio":{"type":"string","description":"Output aspect ratio","enum":["1:1","4:3","3:4","16:9","9:16","3:2","2:3","21:9","1:4","4:1","5:4","4:5"],"default":"1:1"},"quality":{"type":"string","description":"Output resolution","enum":["512","1K","2K","4K"],"default":"2K"},"num_images":{"type":"integer","minimum":1,"maximum":10,"default":1,"description":"Number of images to generate"},"temperature":{"type":"number","minimum":0,"maximum":2,"default":1,"description":"Creativity control. Lower = faithful, higher = creative"},"seed":{"type":"integer","description":"Random seed for reproducibility. Same seed + prompt = same image"},"use_search_grounding":{"type":"boolean","default":false,"description":"Enable real-time Google Search for factual/visual accuracy (Nano Banana Flash only)"},"reference_images":{"type":"array","maxItems":14,"description":"Reference images for character/product consistency (Nano Banana Pro only)","items":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"URL of the reference image"},"description":{"type":"string","maxLength":500,"description":"Description of what to match from this image"}}}},"output_format":{"type":"string","enum":["jpeg","png","webp"],"description":"Output image format"},"image_urls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Input image URLs for image-to-image generation"},"strength":{"type":"number","minimum":0,"maximum":1,"description":"Strength of image transformation for image-to-image (0-1)"},"num_inference_steps":{"type":"integer","description":"Number of diffusion steps (model-dependent)"},"guidance_scale":{"type":"number","description":"Classifier-free guidance scale"},"background":{"type":"string","enum":["transparent","opaque","auto"],"description":"Background mode"},"colors":{"type":"array","maxItems":5,"items":{"type":"string"},"description":"Color palette constraints"},"style":{"type":"string","description":"Style preset"},"image_size":{"type":"string","description":"Output resolution (Imagen models)","enum":["1K","2K"]},"enhance_prompt":{"type":"boolean","description":"Let the model enhance your prompt (Imagen models)"},"add_watermark":{"type":"boolean","description":"Add invisible watermark (Imagen models)"},"person_generation":{"type":"string","enum":["dont_allow","allow_adult","allow_all"],"description":"Person generation policy (Imagen models)"},"safety_filter_level":{"type":"string","enum":["block_low_and_above","block_medium_and_above","block_only_high","block_none"],"description":"Safety filter level (Imagen models)"},"output_compression_quality":{"type":"integer","minimum":0,"maximum":100,"description":"JPEG compression quality (Imagen models)"},"call_webhook":{"type":"boolean","default":false,"description":"Send a POST callback when generation completes"},"webhook_url":{"type":"string","format":"uri","description":"Webhook destination URL. Required when `call_webhook` is true"},"webhook_secret":{"type":"string","description":"Secret sent as `x-webhook-secret` header in the webhook callback"}}},"ImageGenerateResponse":{"type":"object","properties":{"task_id":{"type":"string"},"status":{"type":"string","enum":["completed","pending","failed"]},"output":{"type":"object","properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"URL of the generated image"}}}}}},"usage":{"type":"object","properties":{"cost_usd":{"type":"number","description":"Cost in USD (includes margin)"},"images_generated":{"type":"integer"}}}}},"AsyncTaskResponse":{"type":"object","properties":{"task_id":{"type":"string","description":"Use this ID to poll GET /tasks/{task_id}"},"status":{"type":"string"},"output":{"nullable":true,"description":"null until task completes"}}},"APIError":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"type":{"type":"string","enum":["invalid_request_error","provider_rate_limit_error","provider_error","server_error"]},"param":{"type":"string","nullable":true},"code":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"InsufficientCredit":{"description":"Organization has insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"paths":{"/images/generate":{"post":{"tags":["Image Generation"],"summary":"Generate images","operationId":"imageGenerate","description":"Generate images from text prompts. See the model-specific guides below for detailed usage.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerateRequest"}}}},"responses":{"200":{"description":"Synchronous generation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImageGenerateResponse"}}}},"202":{"description":"Async task created — poll GET /tasks/{task_id}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncTaskResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientCredit"},"502":{"description":"Upstream provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"}}}}}}}}}
```

## List image models

> Retrieve all available image generation models with capabilities and supported formats.

```json
{"openapi":"3.0.3","info":{"title":"Qolaba Image Generation API","version":"1.0.0"},"tags":[{"name":"Image Generation","description":"Generate images from text prompts"}],"servers":[{"url":"https://api.platform.qolaba.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key passed as a Bearer token.\nGenerate your key at [platform.qolaba.ai](https://platform.qolaba.ai).\nExample: `Authorization: Bearer sk-xxxxxxxxxxxx`\n"}},"schemas":{"ImageModel":{"type":"object","properties":{"id":{"type":"string"},"model":{"type":"string"},"provider":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}},"supported_formats":{"type":"array","items":{"type":"string"}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"InsufficientCredit":{"description":"Organization has insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"paths":{"/images/models":{"get":{"tags":["Image Generation"],"summary":"List image models","operationId":"getImageModels","description":"Retrieve all available image generation models with capabilities and supported formats.","responses":{"200":{"description":"List of image models","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ImageModel"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientCredit"}}}}}}
```

## Get task status

> Poll the status of an async task (e.g. image generation with \`mode: "async"\`).\
> Keep polling until \`status\` is \`completed\` or \`failed\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Qolaba Image Generation API","version":"1.0.0"},"tags":[{"name":"Tasks","description":"Poll async task status"}],"servers":[{"url":"https://api.platform.qolaba.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key passed as a Bearer token.\nGenerate your key at [platform.qolaba.ai](https://platform.qolaba.ai).\nExample: `Authorization: Bearer sk-xxxxxxxxxxxx`\n"}},"schemas":{"TaskResponse":{"type":"object","properties":{"task_id":{"type":"string"},"status":{"type":"string","enum":["pending","completed","success","failed"]},"output":{"type":"object","nullable":true,"properties":{"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}},"usage":{"type":"object","properties":{"cost_usd":{"type":"number"},"images_generated":{"type":"integer"}}}}}}}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"InsufficientCredit":{"description":"Organization has insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}}}},"paths":{"/tasks/{task_id}":{"get":{"tags":["Tasks"],"summary":"Get task status","operationId":"getTask","description":"Poll the status of an async task (e.g. image generation with `mode: \"async\"`).\nKeep polling until `status` is `completed` or `failed`.\n","parameters":[{"name":"task_id","in":"path","required":true,"description":"The task ID returned by an async operation","schema":{"type":"string"}}],"responses":{"200":{"description":"Task status and results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientCredit"}}}}}}
```