Skip to main content
The API Reference section documents each endpoint, request parameter, and response schema from the OpenAPI specification. Endpoint pages include an interactive playground so you can test requests directly from the documentation. This page summarizes the conventions shared by all endpoints.

​
Base URL and versioning

Base URLhttps://aigenstudio.app
Version prefix/api/v1
FormatJSON UTF-8
Breaking changes require a new version path such as /api/v2. The /api/v1 contract remains stable within the current API version.

​
Authentication

Send your API key with the Authorization header on every authenticated request. 
Authorization: Bearer aigen_live_xxxxxxxxx
Sandbox keys start with aigen_test_. Live keys start with aigen_live_. The presets endpoint is public. Enhancement creation and status endpoints require an API key.

​
Required request headers

HeaderRequired onDescription
AuthorizationAuthenticated endpointsBearer API key.
Content-Type: application/jsonPOST requestsJSON request body.
Idempotency-KeyPOST /api/v1/product-image-enhancementsStable key for safe retries.
X-Request-IdOptionalClient correlation id. Also returned by AI Gen Studio.
Do not send the idempotency key in the JSON body. The header is the source of truth.

​
Success responses

Create and status endpoints return an enhancement object. 
{
  "enhancement": {
    "id": "f693e677-51e0-4ebe-80a0-ad06acbc4443",
    "status": "queued",
    "total_items": 1,
    "credits_reserved": 5,
    "sandbox": false
  },
  "remaining_paid_credits": 85,
  "request_id": "req_..."
}
Preset listing returns a presets array. 
{
  "presets": [
    {
      "id": "single_product_white_background",
      "name": "Single product white background",
      "description": "Best for one clear product that should be isolated on a clean white or very light neutral ecommerce background."
    }
  ],
  "request_id": "req_..."
}

​
Error responses

Errors use a stable envelope. 
{
  "error": {
    "code": "invalid_payload",
    "message": "The product image enhancement payload is invalid.",
    "request_id": "req_..."
  }
}
Use request_id when contacting support or correlating responses with logs. See Errors for retry guidance and common error codes.

​
Asynchronous processing

Image enhancement is asynchronous.
  1. Create an enhancement with one to 20 source images.
  2. Store enhancement.id and your own external_id values.
  3. Poll the status endpoint or receive signed webhook events.
  4. Attach successful result_url values to the matching product records.
Enhancement statuses: 
queued
processing
completed
partially_completed
failed
cancelled

​
Rate limit headers

Rate-limited responses may include:
HeaderDescription
Retry-AfterSeconds to wait before retrying.
X-RateLimit-LimitLimit for the current window.
X-RateLimit-RemainingRemaining requests in the current window.
X-RateLimit-ResetUnix timestamp when the window resets.
See Rate limits for the current limits.

​
Unsupported authentication methods

Only Bearer API keys are supported. The following are rejected:
  • API keys in query strings;
  • x-api-key or other custom API key headers;
  • cookies or session tokens;
  • user JWTs instead of AI Gen Studio API keys.