> ## Documentation Index > Fetch the complete documentation index at: https://docs.adskull.io/llms.txt > Use this file to discover all available pages before exploring further. # Images > Generate AI images across 15 models with full ratio and quality control. Use image generation for product shots, ad creative, hero images, social posts, and reference frames for video. ## Endpoints | Method | Endpoint | Purpose | | ------ | -------------------------------- | ------------------------------- | | `POST` | `/v1/image-generations` | Create an image-generation job. | | `GET` | `/v1/image-generations` | List recent image jobs. | | `GET` | `/v1/image-generations/{job_id}` | Get one image job. | ## Orientation cheatsheet `ratio` is validated **per model**: any ratio the model advertises in [Models](/public/models#image-models) (or `GET /v1/models`) is accepted, and anything else returns `400 invalid_request` with the accepted list in the error message. | You want | Pass `ratio` | Supported by | | ------------------------------------------------ | ---------------------------------- | --------------------------------------------------------------- | | Vertical / portrait (Stories, Reels covers) | `"9:16"` | all models except `gpt-image-1-5` | | Horizontal / landscape (web hero, YouTube thumb) | `"16:9"` | all models except `gpt-image-1-5` | | Square (Instagram feed) | `"1:1"` | all models | | Instagram portrait (4:5) | `"4:5"` | `nano-banana-pro`, `nano-banana-2`, `nano-banana-2-lite` | | Portrait / landscape product | `"3:4"` / `"4:3"` | most models | | Classic photo | `"2:3"` / `"3:2"` | nano-banana, flux, seedream, grok, gpt-image models | | Ultrawide / cinematic | `"21:9"` | nano-banana, seedream, wan, gpt-image-2 | | Extreme banner strips | `"1:4"`, `"4:1"`, `"1:8"`, `"8:1"` | `nano-banana-2`/`-lite` (all four), `wan-2-7`/`-pro` (1:8, 8:1) | ## Create Parameters | Field | Type | Required | Notes | | ---------------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model_id` | string | **Yes** | One of: `nano-banana-pro`, `nano-banana-2`, `nano-banana-2-lite`, `flux-2-pro`, `flux-2`, `seedream-4-5`, `seedream-5-lite`, `wan-2-7-pro`, `wan-2-7`, `ideogram-v3`, `grok-imagine`, `qwen2`, `gpt-image-2`, `gpt-image-1-5`, `z-image`. | | `prompt` | string | **Yes** | Description of the image. Max 4096 chars. | | `ratio` | string | No | Any ratio the model supports (see [Models](/public/models#image-models)). Defaults to the model's default ratio. | | `quality` | string | No | Per-model. `1K`/`2K`/`4K` for nano-banana and `gpt-image-2`, `1K`/`2K` for flux, `TURBO`/`BALANCED`/`QUALITY` for `ideogram-v3`, `STANDARD`/`QUALITY` for `grok-imagine`, `basic`/`high` for `seedream-5-lite`, `medium`/`high` for `gpt-image-1-5`, `default` for the rest (incl. `nano-banana-2-lite`, fixed 1K). Omit to use the model default. | | `count` | integer | No | 1–4. Defaults to `1`. `grok-imagine` always returns 2–6 images per run regardless. | | `reference_image_url` | string | No | One hosted image URL. SSRF-checked. Use `POST /v1/assets` to host local files. Rejected by `z-image` (text-to-image only). | | `reference_image_urls` | string\[] | No | Alias accepted for compatibility; only the **first** URL is used. | | `negative_prompt` | string | No | Content to avoid (≤ 1024 chars). | `Idempotency-Key` is **required** on every `POST /v1/image-generations`. ## Example: vertical product shot with Nano Banana Pro ```bash theme={"theme":"github-dark"} curl https://api.adskull.io/v1/image-generations \ -H "Authorization: Bearer $ADSKULL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: img-vertical-001" \ -d '{ "model_id": "nano-banana-pro", "prompt": "Iced coffee can on white marble, soft morning sunbeam", "ratio": "9:16", "quality": "2K", "count": 2 }' ``` ## Example: hero banner with Flux-2 Pro ```bash theme={"theme":"github-dark"} curl https://api.adskull.io/v1/image-generations \ -H "Authorization: Bearer $ADSKULL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: img-hero-001" \ -d '{ "model_id": "flux-2-pro", "prompt": "Sleek SaaS dashboard hero with abstract waveforms behind it", "ratio": "16:9", "quality": "2K" }' ``` ## Example: Grok Imagine bulk creative ```bash theme={"theme":"github-dark"} curl https://api.adskull.io/v1/image-generations \ -H "Authorization: Bearer $ADSKULL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: grok-bulk-001" \ -d '{ "model_id": "grok-imagine", "prompt": "Bold cyberpunk product flyer, neon typography", "ratio": "1:1", "quality": "QUALITY" }' ``` ## Example: Instagram portrait (4:5) with Nano Banana Pro ```bash theme={"theme":"github-dark"} curl https://api.adskull.io/v1/image-generations \ -H "Authorization: Bearer $ADSKULL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: img-ig45-001" \ -d '{ "model_id": "nano-banana-pro", "prompt": "Skincare serum bottle on travertine, golden-hour shadowplay", "ratio": "4:5", "quality": "2K" }' ``` ## Example: cheap draft render with Z-Image ```bash theme={"theme":"github-dark"} curl https://api.adskull.io/v1/image-generations \ -H "Authorization: Bearer $ADSKULL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: img-zdraft-001" \ -d '{ "model_id": "z-image", "prompt": "Minimal flat-lay of running shoes on pastel background", "ratio": "1:1" }' ``` ## Example: image edit with references (Nano Banana 2) ```bash theme={"theme":"github-dark"} # 1) Upload your reference curl https://api.adskull.io/v1/assets \ -H "Authorization: Bearer $ADSKULL_API_KEY" \ -F asset_type=image \ -F file=@./brand-style.png # 2) Generate using it as a reference curl https://api.adskull.io/v1/image-generations \ -H "Authorization: Bearer $ADSKULL_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: img-ref-001" \ -d '{ "model_id": "nano-banana-2", "prompt": "Apply the brand style to a new energy-drink can", "ratio": "9:16", "quality": "2K", "reference_image_urls": ["https://cdn.adskull.io/uploads/..."] }' ``` ## Accepted Response ```json theme={"theme":"github-dark"} { "id": "job_01HXIMG...", "object": "image_generation_job", "status": "queued", "credits_reserved": 12, "credits_used": null, "created_at": "2026-05-17T12:00:00Z", "assets": [] } ``` ## Completed Response ```json theme={"theme":"github-dark"} { "id": "job_01HXIMG...", "object": "image_generation_job", "status": "completed", "credits_reserved": 12, "credits_used": 12, "completed_at": "2026-05-17T12:00:09Z", "assets": [ { "id": "asset_01HX...", "type": "image", "url": "https://cdn.adskull.io/generated/image.png", "mime_type": "image/png", "width": 1080, "height": 1920, "expires_at": "2026-05-18T12:00:09Z" } ] } ``` ## Possible Errors | HTTP | Code | When it happens | | ---: | -------------------------- | ------------------------------------------------------------------- | | 400 | `invalid_request` | Unknown model, unsupported ratio/quality, or invalid reference URL. | | 401 | `unauthorized` | API key missing or invalid. | | 402 | `insufficient_credits` | Not enough credits. | | 422 | `content_policy_violation` | Prompt or reference image not allowed. | | 429 | `rate_limited` | Too many requests. | | 503 | `temporarily_unavailable` | Provider capacity temporarily unavailable. |