Transform raw product images into polished ad creatives using AI-powered generation.
This API handles background removal, automatic product tagging, and creative generation through fine-tuned AI models. It allows for both predefined style presets and fully custom prompts, and returns studio-grade ad visuals from simple product photos.
⚙️ How It Works
The generation engine is powered by:
Fine-Tuned Stable Diffusion Inpainting
A fine-tuned version of Stable Diffusion Inpainting, optimized for product placement use cases. It seamlessly embeds products into masked scene regions, maintaining realism and fidelity through domain-specific training.
🔁 Basic Flow
Authenticate via /Authorization/GenerateJwtToken
Upload a product photo using /ProductGeneration/Recommendations
Automatically extracts:
✅ Product name & description
✅ Background-removed image (imageId)
✅ Prompt recommendations
✅ Best-matching presetIds from /ProductGeneration/PresetKeys
Start generation via /Image/ProductGeneration/AdCreative using the imageId
Track progress via /Image/ProductGeneration/CheckUserProgress
Completion when: progress = 100 and all 6 tasks return renderState = 5
Optional: Configure webhook via /NotificationChannel for real-time updates
Download assets via /Image/ProductGeneration/Download
Use imageProductGeneratorProcessId + taskId
Options:
lowResolution = true/false
format = 0 (PNG) | 1 (JPEG) | 2 (PDF 1.6)
🧠 Prompt Handling
PromptObjectsString (MAX 6 prompts):
[
{
"tag": "custom",
"prompt": "on a sleek black and blue geometric pattern background...",
"nativeLanguagePrompt": null
},
{
"preset": "white_pink_yellow_gradient_background_monochrome",
"tag": "preset"
},
{
"tag": "custom",
"prompt": "custom style prompt",
"nativeLanguagePrompt": null
}
]
custom: freeform style prompt
preset: predefined styles from /ProductGeneration/PresetKeys
Pass as a stringified array in the request body.
🎨 Presets
GET/api/v1/Image/ProductGeneration/PresetKeys
Retrieve predefined prompt styles categorized into groups like "monochrome", "studio", or "holiday".
[
{
"id": "on_platform_natural_beige_background",
"previewImageUrl": "https://api.adcreative.ai/assets/ai-product-preset/on_platform_natural_beige_background.webp",
"previewName": "On Platform Natural Beige Background",
"promptText": "on a platform, in front of a natural beige background",
"categories": [{ "name": "monochrome" }]
},
{
"id": "thanksgiving_rustic_scene",
"previewImageUrl": "https://api.adcreative.ai/assets/ai-product-preset/thanksgiving_rustic_scene.webp",
"previewName": "Thanksgiving Rustic Scene",
"promptText": "product on rustic wood table with autumn leaves and warm lighting, thanksgiving style",
"tags": ["holiday", "thanksgiving"]
}
]
Presets may include category-based or tag-based filters.
Some seasonal/holiday presets appear under "All" via internal tag logic.
⚠️ Common Error Scenarios
File too large
Error while removing background:
{
"errors": [
{
"title": "File too large",
"code": "file_too_large",
"detail": "File exceeds limit of 22MB"
}
]
}
→ Ensure images are in JPG or PNG format and are no larger than 22 MB.
Unknown foreground
Error while removing background:
{
"errors": [
{
"title": "Could not identify foreground in image",
"code": "unknown_foreground"
}
]
}
→ Ensure your image has a well-defined object or product against a distinct background
✅ Tips for Best Results
Foreground subject should be clear and well-lit
Use simple backgrounds, avoid clutter
Minimize shadows, reflections, and logos
Ensure the product is fully visible, not cropped
📋 GET /ProductGeneration/PresetKeys
Retrieve available preset configurations for product photo generation.
Endpoint
GET /api/v1/Image/ProductGeneration/PresetKeys
Query Parameters
Name
Type
Required
Description
applicationId
GUID
Yes
The unique ID representing your application.
userId
GUID
Yes
The user ID under the application, used to scope presets.
{
"productInfo": {
"productName": "headphones",
"productDescription": "Wireless over-ear headphones with noise-canceling features in vibrant red and black."
},
"backgroundRemovedImageAssetId": "ecc767e4-c107-4492-9826-89756e925425",
"recommendedPrompts": [
"on a sleek glass surface with a reflection of city skyscrapers...",
"on a dynamic music waveform graphic...",
"on a velvet cushion inside a luxurious music studio...",
"on a vibrant graffiti wall in an urban alley..."
],
"recommendedPresetIds": [
"natural_beige_background",
"white_background",
"light_grey_background",
"light_blue_background",
"gray_shadowy_room_sunlight_streaming_studio",
"gray_shadowy_room_sunlight_streaming_neutral"
]
}
Error Responses
Missing Token or Invalid Token
{
"errors": {
"business:": [
"Token is missing, invalid or ApplicationId is not found in the token."
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more errors occurred.",
"status": 401,
"detail": null,
"instance": null,
"extensions": {
"traceId": "00-6865a20820da1254cdd62ef5de9df71e-60781c154d97f7c6-00"
}
}
Missing or Invalid File Upload
{
"errors": {
"productImage": [
"The productImage field is required.",
"The request does not contain a file. Please make sure to upload the file."
]
},
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-1342e34cfbba2b448dcaefe49e0b67d6-a3d4e02dd4b7f122-00"
}
📸 /ProductGeneration/AdCreative Endpoint
POST/api/v1/Image/ProductGeneration/AdCreative
This endpoint is the core of the Product Photoshoot feature. It takes in a background-removed product image and returns multiple ad creatives generated using preset-based or custom prompts.
Image Asset ID retrieved from /ProductGeneration/Recommendations
PromptObjectsString
✅
string
JSON string containing an array of prompt objects (preset or custom)
productName
✅
string
Product name (recommended: extracted from /Recommendations)
productDescription
✅
string
Product description (recommended: extracted from /Recommendations)
DisableSafeMargin
❌
boolean
When true, returns images in strict 1200x628 instead of 1674x628 (see below)
UseSameStyleReferenceImage
❌
boolean
When true (default), uses the style, background and color palette from the preset image
🖼️ Image Dimensions Behavior (DisableSafeMargin)
By default, generated images are 1674x628, offering safe margins to allow for design alignment (e.g. centering or left/right placement of products). This provides flexibility in use cases where further cropping or positioning is needed.
DisableSafeMargin = true: returns exact 1200x628 images (no margins)
DisableSafeMargin = false or omitted: returns 1674x628 images with safe zones for alignment
🎨 UseSameStyleReferenceImage
When enabled (default), the preset’s background — represented by its previewImageUrl — is used as a visual style guide during generation. The AI blends the style and color palette from the preset image (e.g., white background, studio, floral themes) with the product image’s dominant colors to create a more personalized and brand-consistent Product Photoshoot.
For example, given a preset like:
{
"id": "white_background",
"previewImageUrl": "https://api.adcreative.ai/assets/ai-product-preset/white_background.webp",
"previewName": "White Background",
"promptText": ", in front of a white background",
"categories": [ { "name": "monochrome" } ]
}
...if UseSameStyleReferenceImage is set to true, the AI will consider both the white background style and the uploaded product’s color scheme when composing the final output image.
🧪 Example curl Request
curl --location 'https://api.adcreative.ai/api/v1/Image/ProductGeneration/AdCreative' \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'x-api-key: f8a3d2c6e9b1a7d4c5f0e6b3a9d7c2f1' \
--header 'X-API-SECRET: b7e4c1d9a5f2e8c6d3a9b0f1c7e2d5a3f6b8c9a1d4e7f0b3c2a5d9f6e1b7c4a8' \
--form 'applicationId="6a9d3f2c-1b0e-4c7f-a8d5-e3f0c1b9a4d6"' \
--form 'userId="2f1e3c4d-5b6a-4d8f-9c01-e2d3c4b5f6a7"' \
--form 'renderKind="4"' \
--form 'productImageAssetId="d7f5c3b1-c029-4df5-8908-896ab0c1f24d"' \
--form 'PromptObjectsString="[{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"},{\"preset\":\"mid_century_modern_office\",\"tag\":\"preset\"}]"' \
--form 'productName="vodka bottle"' \
--form 'productDescription="A clear glass bottle of vodka with blue and black text, set against a marble background with green leaves."' \
--form 'DisableSafeMargin="true"' \
--form 'UseSameStyleReferenceImage=""'
This endpoint is used to retrieve generated product visuals based on a taskId and imageProductGeneratorProcessId. It supports optional format and resolution flags.
🔗 Endpoint
GET /api/v1/Image/ProductGeneration/Download
📥 Query Parameters
Name
Type
Required
Description
applicationId
Guid
✅ Yes
Unique identifier of the application
taskId
Guid
✅ Yes
ID of the individual generation task
imageProductGeneratorProcessId
Guid
✅ Yes
ID of the overall product generation process
lowResolution
Boolean
❌ No
Default: false. Whether to return a low-resolution version.
format
Integer
❌ No
Format of the image: 0=PNG (default), 1=JPEG, 2=PDF
Returns the image as a file stream or downloadable content. If an error occurs, the following structure may be returned:
{
"errors": {
"engine: ProductGeneration/Download": [
"Image content not found."
],
"business: ProductGeneration/Download": [
"Not found error occurred while getting image content stream"
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more errors occurred.",
"status": 404,
"detail": null,
"instance": null,
"extensions": {
"traceId": "00-599b17ae93900d22ce7df8169f3188f6-edcd222ed89634ed-00"
}
}
📝 Download Behavior
lowResolution
format
Description
false
0 (PNG)
Original high-res PNG is served as-is
false
1 (JPEG)
High-res PNG is converted to JPEG
true
1 (JPEG)
Thumbnail JPEG served as-is
true
0 (PNG)
Thumbnail JPEG is converted to PNG (increased file size due to full color)
false
2 (PDF)
Original is embedded into PDF 1.6
true
2 (PDF)
Thumbnail is embedded into PDF 1.6
❗️Common Error Responses
401 Unauthorized
{
"errors": {
"business:": [
"Token is missing, invalid or ApplicationId is not found in the token."
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more errors occurred.",
"status": 401,
"detail": null,
"instance": null,
"extensions": {
"traceId": "00-6865a20820da1254cdd62ef5de9df71e-60781c154d97f7c6-00"
}
}
400 Bad Request – API Key Credits for Application does not exist
{
"errors": {
"engine: ProductGeneration/Download": [
"Error decreasing Api Key Credits for Application e790c565-d56a-4e32-b00a-66be90cfcd43. ErrorMessage: API Key Credits for Application does not exist."
],
"business: ProductGeneration/Download": [
"Bad request error occurred while getting image content stream"
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more errors occurred.",
"status": 400,
"detail": null,
"instance": null,
"extensions": {
"traceId": "00-5593df94b6415482f5d01c65f51de46f-9a0a8bfb206eae96-00"
}
}
400 Bad Request – Validation Error
{
"errors": {
"imageProductGeneratorProcessId": [
"The value '60a743a6-c761-4168-9288-40a729dd407e1' is not valid."
]
},
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "00-ae0c64f2970933d69b2a159253a68fea-9e4a75471688ac32-00"
}
