Skip to main content
Use batch processing when a merchant imports a catalog or when your platform syncs a group of product images. Each batch can contain up to 20 images.

​
Batch shape

{
  "preset": "marketplace_clean_catalog",
  "preservation_level": "strict",
  "images": [
    {
      "external_id": "sku_001",
      "source_url": "https://cdn.example.com/catalog/sku_001.jpg"
    },
    {
      "external_id": "sku_002",
      "source_url": "https://cdn.example.com/catalog/sku_002.jpg"
    }
  ]
}
external_id should be stable in your system. It is returned in status responses and webhook events so you can update each product record.

​
Batch size

Maximum images per batch: 20
Processed images per hour per API key: 25
Active batches per API key: 1
Active batches per account: 2
For a large catalog, enqueue batches on your side and submit the next batch after the current one reaches a terminal state.

​
Idempotency

Use one idempotency key per logical batch. 
Idempotency-Key: merchant-42-import-2026-06-22-page-1
If your create request times out, retry with the same key and exact same body. AI Gen Studio returns the existing enhancement instead of creating a duplicate.

​
Handling partial success

A batch can become partially_completed when some items complete and others fail. Your integration should:
  • save successful item result_url values;
  • show failed items to an operator or retry queue;
  • retry failed items with a new idempotency key only after the source input has been fixed or the failure is retryable.

​
Webhooks for batch imports

For catalog imports, webhooks are recommended. Use item events to update individual products and enhancement events to mark the import batch as finished. Polling remains useful as a fallback and source of truth if webhook delivery is delayed.