Batch API

Overview

A batch lets an integrator launch a campaign of up to 100 image or video jobs without wrangling dozens of request lifecycles. Submit the list once, persist the returned ID, and poll until the server reports a final state. Authentication accepts the same sk-ag-* API key as the single-generation endpoints or a user JWT.

Lifecycle

A batch starts at queued, moves to in_progress, then ends as completed, failed, or partial.

Create a batch

Send exactly one JSON body with kind and a list of request items. The examples use three prompts; expand the same list to 20 or more for a campaign.

curl https://api.aggregate.ai/v1/batches \
  -H "Authorization: Bearer sk-ag-..." -H "Content-Type: application/json" \
  -d '{
    "kind": "image",
    "requests": [
      {"model":"image-standard","prompt":"A red fox in a snowy pine forest","size":"1024x1024"},
      {"model":"image-standard","prompt":"A blue heron beside a quiet lake at dawn","size":"1024x1024"},
      {"model":"image-standard","prompt":"A ceramic studio with warm afternoon light","size":"1024x1024"}
    ],
    "metadata": {"campaign":"winter-collection"}
  }'

The 202 response contains id, kind, status, job counters, timestamps, optional webhook URL, and metadata. Response headers also include X-Batch-Id and X-Total-Jobs.

Poll for results

Poll every two seconds and stop at a final batch state. Polling is the Phase 1 delivery mechanism.

while true; do
  batch=$(curl -s https://api.aggregate.ai/v1/batches/BATCH_ID \
    -H "Authorization: Bearer sk-ag-...")
  status=$(echo "$batch" | jq -r .status)
  echo "$status: $(echo "$batch" | jq -r .completed_jobs)/$(echo "$batch" | jq -r .total_jobs)"
  case "$status" in completed|failed|partial) echo "$batch"; break;; esac
  sleep 2
done

Read individual job results

{
  "seq": 0,
  "status": "succeeded",
  "url": "/media/asset-id",
  "error_code": null,
  "error_message": null
}

A successful job has a non-null url. A failed job has url: null; use its error fields for retry or reporting.

List your batches

curl "https://api.aggregate.ai/v1/batches?status=queued&status=in_progress&limit=50" \
  -H "Authorization: Bearer sk-ag-..."

Use this filtered list on client reconnect to restore the most recent active batch. Repeat without status filters to display history.

Webhook

Include webhook_url in the create request; when the batch reaches a final status (completed, failed, or partial) we POST a signed event to your URL. The 202 create response contains a one-time webhook_secret — persist it; it is never re-exposed via GET.

Each delivery carries Stripe-style HMAC-SHA256 headers. Verify by recomputing the signature and comparing.

# Incoming headers:
#   X-AggreGate-Signature: t=1721558400,v1=9f3c...
#   X-AggreGate-Event: batch.completed
# Verify (shell):
body=$(cat)
ts=1721558400
sig=$(echo -n "$ts.$body" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | awk '{print $2}')
[ "$sig" = "9f3c..." ] && echo verified

Retries: exponential backoff (2^attempts minutes) up to 5 attempts; after that the batch is marked disabled and no further attempts are made. Respond with any 2xx to acknowledge.

Cancel

curl -X POST "https://api.aggregate.ai/v1/batches/BATCH_ID/cancel" \
  -H "Authorization: Bearer sk-ag-..."

Cancellation is recorded as metadata.cancel_requested_at. Queued jobs are marked cancelled and their units refunded. Running jobs complete normally — upstream cost has already been paid.

Limits

• Maximum 100 items per batch.
• Batch results expire after 7 days.
• Use the API response and account limits as the source of truth for request rate limits.

Pricing

Batch jobs use the same fixed units as single-shot image and video generations. Review current media packages; units are reserved for the submitted jobs.