Developer Reference
API Documentation
Integrate PergAI's world-class image processing directly into your ecommerce engine. Automate product creation and library management with our professional REST API.
Authentication
All requests must include your API key in the Authorization header as a Bearer token.
Authorization Header
Authorization: Bearer pk_YOUR_API_KEYGET
List Products
Returns a list of all products in your library with their metadata and signed image URLs.
GET /api/external/v1/productsResponse Properties
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique identifier for the product record. |
| name | String | The name of the product. |
| category | Enum | Product classification group. |
| imagePath | URL | Signed URL for product image. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/products' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'GET
Retrieve Product
Fetch detailed information about a single product record using its unique ID.
GET /api/external/v1/products/{id}Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id Required | UUID | The unique identifier of the product. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/products/PROD_ID' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'POST
Create Product
Add a new product to your library by providing a name, category, and image path.
POST /api/external/v1/productsRequest Body
| Parameter | Type | Description |
|---|---|---|
| name Required | String | Product identifier name. |
| category Required | String | Classification group. |
| imagePath Required | String | Reference image storage path. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/products' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--data-raw '{
"name": "Classic T-Shirt",
"category": "clothing",
"imagePath": "products/sample.png"
}'DELETE
Delete Product
Permanently remove a product from your library using its unique ID.
DELETE /api/external/v1/products/{id}Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id Required | UUID | The unique identifier of the product to delete. |
Example Request
curl --request DELETE \
--location 'http://localhost:3002/api/external/v1/products/PROD_ID' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'GET
List Generations
Returns a list of all AI-generated images with their metadata and signed URLs.
GET /api/external/v1/generationsResponse Properties
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique identifier for the generation record. |
| productId | UUID | The ID of the source product. |
| status | Enum | Current status: pending, processing, completed, failed. |
| resultImagePath | URL | Signed URL for the generated image. |
| prompt | String | The text prompt used for generation. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/generations' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'GET
List Scene Templates
Returns a list of all available AI scene templates that can be used in the generation API.
GET /api/external/v1/templatesExample Request
curl --location 'http://localhost:3002/api/external/v1/templates' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'GET
Retrieve Generation
Fetch detailed information about a single AI generation using its unique ID.
GET /api/external/v1/generations/{id}Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id Required | UUID | The unique identifier of the generation. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/generations/GEN_ID' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'POST
Create Generation
Trigger a new AI scene generation for an existing product using professional models.
POST /api/external/v1/generationsRequest Body
| Parameter | Type | Description |
|---|---|---|
| productId Required | UUID | The ID of the source product. |
| scene Required | String | Predefined scene name (e.g., 'studio', 'nature', 'luxury'). You can get the full list from the List Scene Templates API. |
| customPrompt | String | Optional custom prompt to refine the scene. |
| aiProvider | String | AI model to use (default: 'nano-banana'). |
| aspectRatio | String | Target aspect ratio (e.g., '1:1', '16:9'). |
Example Request
curl --location 'http://localhost:3002/api/external/v1/generations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--data-raw '{
"productId": "PROD_ID",
"scene": "studio",
"aiProvider": "nano-banana-pro"
}'GET
List Collections
Returns a list of all your image collections with their items count and preview images.
GET /api/external/v1/collectionsResponse Properties
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique identifier for the collection. |
| name | String | Name of the collection. |
| _count.items | Number | Number of items in the collection. |
| items | Array | Array of the latest 4 items (with signed image URLs) for preview. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/collections' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'POST
Create Collection
Create a new empty collection to organize your AI generations.
POST /api/external/v1/collectionsRequest Body
| Parameter | Type | Description |
|---|---|---|
| name Required | String | The name of the collection. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/collections' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--data-raw '{
"name": "Summer Collection"
}'GET
Retrieve Collection
Returns the details of a specific collection including all its items with signed image URLs.
GET /api/external/v1/collections/[id]Response Properties
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique identifier for the collection. |
| name | String | Name of the collection. |
| items | Array | Full array of items in the collection, featuring signed generation image URLs. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/collections/COLLECTION_ID' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'DELETE
Delete Collection
Permanently delete a collection. This won't delete the actual images, only the collection itself.
DELETE /api/external/v1/collections/[id]Example Request
curl --location --request DELETE 'http://localhost:3002/api/external/v1/collections/COLLECTION_ID' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'POST
Add Image to Collection
Add an existing AI generation to one of your collections.
POST /api/external/v1/collections/[id]/itemsRequest Body
| Parameter | Type | Description |
|---|---|---|
| generationId Required | UUID | The ID of the AI generation to add. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/collections/COLLECTION_ID/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--data-raw '{
"generationId": "GEN_ID"
}'GET
Download Collection ZIP
Download all images in a collection as a single ZIP file.
GET /api/external/v1/collections/[id]/downloadExample Request
curl --location 'http://localhost:3002/api/external/v1/collections/COLLECTION_ID/download' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--output collection.zipPOST
Remove Background
Professionally remove the background from a product image using AI tools.
POST /api/external/v1/tools/remove-bgRequest Body
| Parameter | Type | Description |
|---|---|---|
| productId Required | UUID | The ID of the source product. |
Example Request
curl --location 'http://localhost:3002/api/external/v1/tools/remove-bg' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--data-raw '{
"productId": "PROD_ID"
}'POST
Upscale Image
Enhance and increase the resolution of a product image using professional AI models.
POST /api/external/v1/tools/upscaleRequest Body
| Parameter | Type | Description |
|---|---|---|
| productId Required | UUID | The ID of the source product. |
| scale | String | Target scale (e.g., '1x', '2x', '4x'). Default: '1x'. |
| aiProvider | String | AI model to use (default: 'nano-banana-2'). |
| width | Number | Original image width. |
| height | Number | Original image height. |
| useSharp | Boolean | Use Sharp for pre-processing (default: true). |
Example Request
curl --location 'http://localhost:3002/api/external/v1/tools/upscale' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--data-raw '{
"productId": "PROD_ID",
"scale": "2x",
"aiProvider": "nano-banana-2"
}'POST
Expand Image
Generatively expand the background and change the aspect ratio of a product image.
POST /api/external/v1/tools/expandRequest Body
| Parameter | Type | Description |
|---|---|---|
| productId Required | UUID | The ID of the source product. |
| ratio Required | String | Target aspect ratio (e.g., '1:1', '16:9', '9:16'). |
| prompt | String | Refine the expanded area with text description. |
| aiProvider | String | AI model to use (default: 'nano-banana'). |
| resolution | String | Output resolution (e.g., '1024x1024', '4k'). |
Example Request
curl --location 'http://localhost:3002/api/external/v1/tools/expand' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--data-raw '{
"productId": "PROD_ID",
"ratio": "16:9",
"prompt": "luxury living room background"
}'