Docs/Image Generation API

IMG

Image Generation API

Generate and edit images using AI models with a unified API interface.

Quick Start

Create Task

POST request with model and prompt

Get Task ID

Receive task_id from response

Poll Status

GET request until status is completed

Get Image

Image URL returned in images array

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Supported Models

Model	API Name	Price	Success Rate	Features
Grok 4.2 Image	grok-image/grok-4.2-image	¥0.12/image	-	Text-to-image, URL editing, Mask inpainting
Gemini 2.5 Flash	gemini-2.5-flash-image	$0.20/image	-	Text-to-image, Image editing
Gemini 3 Pro Lite	gemini-3-pro-image-lite	¥0.20-¥0.36	97%	1K/2K/4K output sizes
Gemini 3 Pro	gemini-3-pro-image	¥0.30-¥0.60	99%	1K/2K/4K, Best quality
Gemini 3.1 Flash	gemini-3.1-flash-image-preview	¥0.17-¥0.30	-	1K/2K/4K output sizes
Kling Omni-Image	kling-image-o1	¥0.18	-	1k/2k, Image editing, Multi-image input, Batch (1-9)
Doubao Seedream 5.0 Lite	doubao-seedream-5-0-260128	¥0.20-¥0.30	-	2K/3K, Text-to-image, Image editing, Multi-image fusion
Doubao Seedream 4.5	doubao-seedream-4-5-251128	¥0.20-¥0.40	-	2K/4K, Text-to-image, Image editing
Doubao Seedream 4.0	doubao-seedream-4-0-250828	¥0.20-¥0.40	-	1K/2K/4K, Text-to-image, Image editing

API Endpoints

POST/api/v1/images/generations

Create a new image generation task. Returns a task ID for status polling.

GET/api/v1/images/generations?task_id=xxx

Check task status and retrieve generated images when completed.

task_id: The task ID from create response

Request Parameters (POST)

modelrequiredstring

Model name: grok-image/grok-4.2-image, gemini-2.5-flash-image, gemini-3-pro-image-lite, gemini-3-pro-image, gemini-3.1-flash-image-preview, or kling-image-o1

promptrequiredstring

Text description of the image to generate or editing instructions (max 2500 chars)

image_urlstring

Reference image URL (for image editing, supported by Grok/Gemini/Kling)

imagestring

Base64-encoded image for file-based editing (Grok only, triggers multipart upload)

maskstring

Base64-encoded or URL mask image for inpainting — white areas will be regenerated (Grok only)

image_urlsstring[]

Multiple reference image URLs (for multi-image input, e.g. Kling Omni-Image)

sizestring

Output size: auto, 1024x1024, 1536x1024, 1024x1536 (Grok only, default: auto)

aspect_ratiostring

Output ratio: auto (default), 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 21:9 (Gemini/Kling)

resolutionstring

Output resolution: 1k, 2k, 4k (Gemini/Kling only)

ninteger

Number of images to generate: 1-10 (default: 1, Grok/Kling)

callback_urlstring

Webhook URL - receives POST when task completes

Text to Image (Full Flow)

# 1. Create task
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-lite",
    "prompt": "A futuristic cityscape at sunset with flying cars",
    "aspect_ratio": "16:9",
    "resolution": "2k"
  }'

# Response: {"code":200,"data":{"task_id":"xxx","status":"pending",...}}

# 2. Query status (poll until completed)
curl "https://apimodels.app/api/v1/images/generations?task_id=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response: {"code":200,"data":{"status":"completed","images":["https://..."],...}}

Create Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "cml9xxx...",
    "status": "pending",
    "model": "gemini-3-pro-image-lite"
  }
}

Query Response (Completed)

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "cml9xxx...",
    "status": "completed",
    "model": "gemini-3-pro-image-lite",
    "images": ["https://r2.apimodels.app/images/1770301791772_xxx.jpeg"],
    "created_at": 1738765760416,
    "completed_at": 1738765792304
  }
}

Query Response (Failed)

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "cml9xxx...",
    "status": "failed",
    "model": "gemini-3-pro-image-lite",
    "error": "Content policy violation",
    "created_at": 1738765760416,
    "completed_at": 1738765792304
  }
}

Task Status Values

pendingTask queued, waiting to process

processingTask is being processed

completedSuccess - images array contains URLs

failedFailed - error field contains reason

Image Editing

# Image editing with single reference image (Gemini)
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-lite",
    "prompt": "Add dramatic storm clouds to the sky",
    "image_url": "https://example.com/input.jpg"
  }'

# Kling Omni-Image with all parameters
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-image-o1",
    "prompt": "Change the expression to laughing",
    "image_url": "https://example.com/face.jpg",
    "resolution": "2k",
    "aspect_ratio": "1:1",
    "n": 4
  }'

# Kling multi-image input
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-image-o1",
    "prompt": "Combine these two images into one scene",
    "image_urls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ],
    "resolution": "2k"
  }'

Grok Mask Inpainting

# Grok text-to-image
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-image/grok-4.2-image",
    "prompt": "A cute cat wearing a space helmet, digital art",
    "size": "1024x1024",
    "n": 1
  }'

# Grok URL-based image editing
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-image/grok-4.2-image",
    "prompt": "Change the background to a beach sunset",
    "image_url": "https://example.com/photo.jpg",
    "size": "1024x1024"
  }'

# Grok mask inpainting (base64 image + mask)
curl -X POST https://apimodels.app/api/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-image/grok-4.2-image",
    "prompt": "Replace with a golden retriever",
    "image": "BASE64_ENCODED_IMAGE",
    "mask": "BASE64_ENCODED_MASK",
    "size": "1024x1024"
  }'

Error Codes

400Bad Request - Invalid parameters

401Unauthorized - Invalid or missing API key

402Payment Required - Insufficient credits

404Not Found - Task ID does not exist

500Internal Error - Server error, retry later

Important Notes

-Images are stored for 7 days then automatically deleted
-Failed generations are not charged
-Recommended polling interval: 2-3 seconds
-Use callback_url to avoid polling for production apps

Try in Playground Get API Key