Bulk Images

POST /v1/images/bulk

Generate or edit multiple images in a single request. Ideal for product catalogs, social media batches, and template-based image generation.

Bulk Generation

Generate multiple AI images with different prompts.

curl

curl -X POST https://api.vidiking.com/v1/images/bulk \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "generate",
    "items": [
      {
        "prompt": "Professional headshot on white background, person smiling",
        "model": "flux",
        "width": 1024,
        "height": 1024
      },
      {
        "prompt": "Modern office interior, bright and airy",
        "model": "flux",
        "width": 1920,
        "height": 1080
      },
      {
        "prompt": "Abstract tech background with flowing lines",
        "model": "stable-diffusion",
        "width": 1920,
        "height": 1080
      }
    ],
    "callback": "https://your-server.com/webhooks/vidiking"
  }'

Node.js

const result = await client.images.bulk({
  operation: 'generate',
  items: [
    { prompt: 'Professional headshot on white background', model: 'flux', width: 1024, height: 1024 },
    { prompt: 'Modern office interior, bright and airy', model: 'flux', width: 1920, height: 1080 },
    { prompt: 'Abstract tech background', model: 'stable-diffusion', width: 1920, height: 1080 },
  ],
});

const job = await client.pollJob(result.jobId);
job.images.forEach((img, i) => {
  console.log(`Image ${i + 1}: ${img.url}`);
});

Python

result = client.images.bulk(
    operation="generate",
    items=[
        {"prompt": "Professional headshot on white background", "model": "flux", "width": 1024, "height": 1024},
        {"prompt": "Modern office interior, bright and airy", "model": "flux", "width": 1920, "height": 1080},
        {"prompt": "Abstract tech background", "model": "stable-diffusion", "width": 1920, "height": 1080},
    ],
)

job = client.poll_job(result.job_id)
for i, img in enumerate(job.images):
    print(f"Image {i + 1}: {img.url}")

Bulk Edit

Apply the same editing operations to multiple source images.

curl -X POST https://api.vidiking.com/v1/images/bulk \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "edit",
    "items": [
      { "src": "https://example.com/product1.jpg" },
      { "src": "https://example.com/product2.jpg" },
      { "src": "https://example.com/product3.jpg" },
      { "src": "https://example.com/product4.jpg" }
    ],
    "shared_operations": [
      { "type": "resize", "width": 800, "height": 800, "fit": "cover" },
      { "type": "watermark", "image": "https://example.com/logo.png", "position": "bottom-right", "opacity": 0.3 }
    ],
    "output": { "format": "webp", "quality": 85 }
  }'

Bulk Template Rendering

Generate images from a template with different merge field values.

curl -X POST https://api.vidiking.com/v1/images/bulk \
  -H "Authorization: Bearer $VIDIKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "template",
    "template_id": "img_tpl_social_001",
    "items": [
      { "merge_fields": { "headline": "Summer Sale", "product_image": "https://example.com/p1.jpg" } },
      { "merge_fields": { "headline": "New Arrivals", "product_image": "https://example.com/p2.jpg" } },
      { "merge_fields": { "headline": "Best Sellers", "product_image": "https://example.com/p3.jpg" } }
    ]
  }'

Response

{
  "id": "bulk_abc123",
  "status": "QUEUED",
  "total_items": 3,
  "created_at": "2025-01-15T10:30:00Z"
}

When complete:

{
  "id": "bulk_abc123",
  "status": "COMPLETE",
  "total_items": 3,
  "images": [
    { "index": 0, "url": "https://cdn.vidiking.com/images/bulk_abc123_0.png", "status": "COMPLETE" },
    { "index": 1, "url": "https://cdn.vidiking.com/images/bulk_abc123_1.png", "status": "COMPLETE" },
    { "index": 2, "url": "https://cdn.vidiking.com/images/bulk_abc123_2.png", "status": "COMPLETE" }
  ],
  "credits_used": 12,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:30:30Z"
}

Cost

Bulk operations cost $0.04/image + $0.10 infra fee for generation and 1 credit per image for editing. This is slightly cheaper than individual requests.

Limits

	Limit
Maximum items per request	100
Maximum concurrent bulk jobs	5
Individual image timeout	60 seconds

Partial Failures

If some images in a batch fail, the job still completes. Failed items have a FAILED status with an error message.

{
  "images": [
    { "index": 0, "url": "https://cdn.vidiking.com/...", "status": "COMPLETE" },
    { "index": 1, "status": "FAILED", "error": "Prompt violates content policy" },
    { "index": 2, "url": "https://cdn.vidiking.com/...", "status": "COMPLETE" }
  ]
}

Funds are only charged for successfully generated images.