Skip to main content
POST /api/v1/product-image-enhancements is idempotent per account and API key environment. Send a unique Idempotency-Key for every logical catalog batch. 
Idempotency-Key: catalog-import-2026-06-22-001
The backend that calls AI Gen Studio generates and sends this key. For example, if your marketplace backend creates the enhancement, your marketplace backend should set Idempotency-Key on the request to AI Gen Studio.

​
Why it matters

Network failures can happen after AI Gen Studio accepts an enhancement but before your server receives the response. Idempotency lets you retry the same create request safely. If the same API key owner sends the same idempotency key with the same request body, AI Gen Studio returns the existing enhancement instead of creating another one. This prevents duplicate provider processing and duplicate credit reservations when the caller retries after a timeout, deployment restart, or temporary network failure.

​
Who sends the key

Your integration sends the key in the request header. AI Gen Studio does not generate it for create requests because the caller is the only system that knows which retry belongs to the same logical catalog batch. Use a key that is stable for one batch and unique across different batches.

​
Key requirements

Minimum length: 8 characters
Maximum length: 160 characters
Allowed characters: letters, numbers, dots, underscores, colons, and hyphens
Good examples: 
catalog-import-2026-06-22-001
merchant_42:batch_991
sku-sync.2026-06-22T10:00:00Z

​
Retrying a create request

If your request times out, retry with:
  • the same API key;
  • the same Idempotency-Key;
  • the exact same JSON body.
Do not generate a new idempotency key for a retry unless you intentionally want to create a new enhancement.

​
Conflict behavior

Reusing an idempotency key with a different body returns 409 idempotency_conflict. 
{
  "error": {
    "code": "idempotency_conflict",
    "message": "The idempotency key was already used with a different request body.",
    "request_id": "req_..."
  }
}
When you receive this error, do not keep retrying. Generate a new key only if you are intentionally submitting a new batch. The header is the only supported place for idempotency. Do not send an idempotency field in the JSON body.