Batch AI Image Generation: API Guide

Generating one image at a time works for prototyping. But production workflows need scale: product catalogs with hundreds of variations, social media content calendars, A/B testing campaigns, and automated content pipelines. The batch API endpoint lets you generate up to 50 images in a single request, processed in parallel across multiple GPUs.

This guide covers everything about batch image generation with the ZSky AI API: the endpoint, request format, Python and JavaScript examples, error handling, webhook callbacks, and real-world use cases.

Batch vs. Sequential: Speed Comparison

The batch endpoint is comparable in speed to concurrent individual requests but with significant advantages: a single HTTP connection, atomic error handling, and a 10% pricing discount for subscription users.

Basic Batch Request

Python

import requests

API_KEY = "sk_live_your_api_key"

response = requests.post(
    "https://api.zsky.ai/v1/batch",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "requests": [
            {
                "prompt": "Modern living room, minimalist design, natural light",
                "width": 1024,
                "height": 768,
                "style": "photorealistic"
            },
            {
                "prompt": "Cozy bedroom, warm lighting, plants",
                "width": 1024,
                "height": 768,
                "style": "photorealistic"
            },
            {
                "prompt": "Sleek kitchen, marble countertops, pendant lights",
                "width": 1024,
                "height": 768,
                "style": "photorealistic"
            }
        ]
    },
    timeout=120
)

results = response.json()["results"]
for i, result in enumerate(results):
    if result["status"] == "success":
        print(f"Image {i+1}: {result['image_url']}")
    else:
        print(f"Image {i+1} failed: {result['error']}")

JavaScript

const API_KEY = process.env.ZSKY_API_KEY;

const response = await fetch("https://api.zsky.ai/v1/batch", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    requests: [
      { prompt: "Sunset over the ocean, golden hour", width: 1024, height: 1024 },
      { prompt: "Mountain peak above the clouds", width: 1024, height: 1024 },
      { prompt: "Dense forest after rain, misty", width: 1024, height: 1024 },
      { prompt: "Desert sand dunes at twilight", width: 1024, height: 1024 },
      { prompt: "Tropical waterfall in lush jungle", width: 1024, height: 1024 }
    ]
  })
});

const { results } = await response.json();
results.forEach((result, i) => {
  console.log(`Image ${i + 1}: ${result.status === "success" ? result.image_url : result.error}`);
});

Use Case: Product Catalog Generation

Generate multiple product photography variations from a template description:

import requests
import json

API_KEY = "sk_live_your_api_key"

products = [
    "Ceramic coffee mug, white, on wooden table, morning light",
    "Leather wallet, brown, on marble surface, studio lighting",
    "Canvas tote bag, cream, hanging on wall hook, natural light",
    "Stainless steel water bottle, matte black, outdoor setting",
    "Handmade candle, amber glass jar, cozy background"
]

# Generate 3 angle variations per product
batch_requests = []
for product in products:
    for angle in ["front view", "45-degree angle", "top-down flat lay"]:
        batch_requests.append({
            "prompt": f"{product}, {angle}, product photography, clean background",
            "width": 1024,
            "height": 1024,
            "style": "photorealistic",
            "guidance_scale": 8.0
        })

# Send in batches of 50
for i in range(0, len(batch_requests), 50):
    chunk = batch_requests[i:i+50]
    response = requests.post(
        "https://api.zsky.ai/v1/batch",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"requests": chunk},
        timeout=120
    )

    results = response.json()["results"]
    for j, result in enumerate(results):
        if result["status"] == "success":
            print(f"Product {(i+j)//3 + 1}, angle {(i+j)%3 + 1}: {result['image_url']}")

Use Case: Social Media Content Calendar

const themes = [
  { day: "Monday", prompt: "Motivational quote background, sunrise, warm gradient" },
  { day: "Tuesday", prompt: "Tech tip illustration, modern flat design, blue palette" },
  { day: "Wednesday", prompt: "Behind the scenes workspace, creative mess, warm light" },
  { day: "Thursday", prompt: "Customer testimonial card, professional, clean design" },
  { day: "Friday", prompt: "Weekend vibes, outdoor scene, relaxed atmosphere" },
  { day: "Saturday", prompt: "Product showcase, lifestyle setting, aspirational" },
  { day: "Sunday", prompt: "Reflection and planning, calm workspace, soft tones" }
];

// Generate 4 weeks of content
const requests = [];
for (let week = 1; week <= 4; week++) {
  for (const theme of themes) {
    requests.push({
      prompt: `${theme.prompt}, week ${week} variation, social media post`,
      width: 1024,
      height: 1024
    });
  }
}

// Send in batch (28 images)
const response = await fetch("https://api.zsky.ai/v1/batch", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ requests })
});

const { results } = await response.json();
console.log(`Generated ${results.filter(r => r.status === "success").length} of ${results.length} images`);

Use Case: A/B Testing Ad Variations

base_prompt = "Running shoes on track, dynamic angle, sports photography"

variations = [
    {"style": "photorealistic", "guidance_scale": 7.5},
    {"style": "photorealistic", "guidance_scale": 9.0},
    {"style": "stylized", "guidance_scale": 7.5},
    {"style": "stylized", "guidance_scale": 9.0},
]

color_variants = ["red and white", "black and gold", "blue and silver", "all white"]

batch_requests = []
for color in color_variants:
    for var in variations:
        batch_requests.append({
            "prompt": f"{base_prompt}, {color} colorway",
            "width": 1024,
            "height": 1024,
            **var
        })

# 16 variations in one call
response = requests.post(
    "https://api.zsky.ai/v1/batch",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"requests": batch_requests}
)

Webhook Callbacks

For large batches, use webhook callbacks instead of waiting for the response:

response = requests.post(
    "https://api.zsky.ai/v1/batch",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "requests": batch_requests,
        "webhook_url": "https://your-server.com/api/batch-complete",
        "webhook_events": ["batch.complete", "batch.failed"]
    }
)

# Returns immediately with a batch_id
batch_id = response.json()["batch_id"]
print(f"Batch submitted: {batch_id}")

# Your webhook receives:
# {
#   "event": "batch.complete",
#   "batch_id": "batch_abc123",
#   "results": [{"status": "success", "image_url": "..."}, ...]
# }

Error Handling for Batches

results = response.json()["results"]

succeeded = [r for r in results if r["status"] == "success"]
failed = [r for r in results if r["status"] == "failed"]

print(f"Success: {len(succeeded)}/{len(results)}")
print(f"Failed: {len(failed)}/{len(results)}")

# Retry failed items
if failed:
    retry_requests = [
        batch_requests[i]
        for i, r in enumerate(results)
        if r["status"] == "failed" and r.get("error_code") != "content_policy"
    ]
    if retry_requests:
        retry_response = requests.post(
            "https://api.zsky.ai/v1/batch",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={"requests": retry_requests}
        )

Batch Pricing

Frequently Asked Questions

How many images can I generate in one batch API call?

ZSky AI's batch endpoint accepts up to 50 image generation requests in a single API call. Each request in the batch can have a different prompt, resolution, style, and parameters. The batch processes asynchronously and returns all results when complete.

Is batch image generation cheaper than single calls?

Yes. ZSky AI offers a 10% discount on batch requests for API subscription plan users. Even without the discount, batch processing saves time and reduces network overhead compared to making 50 individual API calls.

Can each image in a batch have different settings?

Yes. Each request in a batch is fully independent. You can set different prompts, resolutions, styles, guidance scales, and output formats for every image in the batch. This makes it ideal for A/B testing variations or generating a diverse product catalog.

What happens if one image in a batch fails?

Failed images in a batch do not affect other images. Each result in the response includes a status field indicating success or failure, plus an error message for failed items. You are only charged for successfully generated images.

How long does batch image generation take?

A batch of 50 standard-resolution images typically completes in 30 to 90 seconds, depending on server load. This is significantly faster than making 50 sequential single-image calls, which would take 3 to 7 minutes. The batch endpoint processes images in parallel on multiple GPUs.