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 (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). 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
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
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
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
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
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)
# 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
{
"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
{
"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. |