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_KEYProducts
GET
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 'https://pergai.com/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 'https://pergai.com/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 'https://pergai.com/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 'https://pergai.com/api/external/v1/products/PROD_ID' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'Categories
GET
List Categories
Returns a full list of all product categories available for classification including their hierarchical structure.
GET /api/external/v1/categoriesResponse Properties
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Unique identifier for the category. |
| nameEn | String | Category name in English. |
| nameTr | String | Category name in Turkish. |
| parentCategoryId | UUID | ID of the parent category (if any). |
| isDefault | Boolean | True if this is a system-provided category. |
Example Request
curl --location 'https://pergai.com/api/external/v1/categories' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'GET
Retrieve Category
Fetch detailed information about a single category using its unique ID.
GET /api/external/v1/categories/{id}Path Parameters
| Parameter | Type | Description |
|---|---|---|
| id Required | UUID | The unique identifier of the category. |
Example Request
curl --location 'https://pergai.com/api/external/v1/categories/CAT_ID' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'POST
Create Category
Add a new category to your library for product classification.
POST /api/external/v1/categoriesRequest Body
| Parameter | Type | Description |
|---|---|---|
| name Required | String | The name of the category. |
| parentCategoryId | UUID | Optional ID of a parent category to create a hierarchy. |
| type | String | Optional display mode hint (e.g., 'scene', 'human'). |
Example Request
curl --location 'https://pergai.com/api/external/v1/categories' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--data-raw '{
"name": "Luxury Accessories",
"parentCategoryId": "PARENT_ID"
}'PUT
Update Category
Modify an existing category's name or hierarchical position using its unique ID.
PUT /api/external/v1/categories/{id}Request Body
| Parameter | Type | Description |
|---|---|---|
| name | String | Updated name. |
| parentCategoryId | UUID | ID of the new parent category. |
| type | String | Updated display mode hint. |
Example Request
curl --request PUT \
--location 'https://pergai.com/api/external/v1/categories/CAT_ID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--data-raw '{
"name": "High-End Jewelry"
}'DELETE
Delete Category
Permanently remove a category from your library using its unique ID.
DELETE /api/external/v1/categories/{id}Example Request
curl --request DELETE \
--location 'https://pergai.com/api/external/v1/categories/CAT_ID' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'Generations
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 'https://pergai.com/api/external/v1/generations' \
--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 'https://pergai.com/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 'https://pergai.com/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"
}'Collections
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 'https://pergai.com/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 'https://pergai.com/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 'https://pergai.com/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 'https://pergai.com/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 'https://pergai.com/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 'https://pergai.com/api/external/v1/collections/COLLECTION_ID/download' \
--header 'Authorization: Bearer pk_YOUR_API_KEY' \
--output collection.zipMagic Tools
POST
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 'https://pergai.com/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 'https://pergai.com/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 'https://pergai.com/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"
}'Templates
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 'https://pergai.com/api/external/v1/templates' \
--header 'Authorization: Bearer pk_YOUR_API_KEY'