Product Photoshoot API

🛍️ Product Photoshoot API Introduction

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

  1. Authenticate via /Authorization/GenerateJwtToken

  2. Upload a product photo using /ProductGeneration/Recommendations

    • Automatically extracts: ✅ Product name & description ✅ Background-removed image (imageId) ✅ Prompt recommendations ✅ Best-matching presetIds from /ProductGeneration/PresetKeys

  3. Start generation via /Image/ProductGeneration/AdCreative using the imageId

  4. 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

  5. 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):

  • 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".

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

→ Ensure images are in JPG or PNG format and are no larger than 22 MB.

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

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.

Example cURL Request

Example Successful Response

Here’s a quick example of how categories vs. tag-based filters work:

  • The first preset (monochrome category) would appear under “All” with a category label.

  • The second one is a holiday-specific preset (Thanksgiving) that doesn’t belong to a category but is surfaced based on name/prompt/tags.

Preset Object Description

Field
Type
Description

id

string

Identifier for the preset

previewImageUrl

string

URL of the preview image

previewName

string

Display name of the preset

promptText

string

Prompt text inserted into the generation prompt

tags

string[]

Optional tags used for internal filtering

categories

object[]

Categories for UI grouping and filtering

isOldPreset

boolean

Whether this preset is marked as legacy or outdated

Notes

  • Presets are logical themes or scene styles for placing your product.

  • Presets may be filtered and grouped by categories, such as monochrome, studio, etc.

  • Seasonal or promotional presets (like Thanksgiving) are surfaced via internal tag or keyword search and may not appear in grouped views.

  • The All section groups presets by category.name.

  • Holiday-specific filters use tag-based logic and may not display category groupings.

POST /ProductGeneration/Recommendations

Transform a single product image upload into a comprehensive generation setup.

Overview

This endpoint processes a product image and provides:

  • Automatically extracted product name & description

  • Background-removed version of the image, returning a unique imageId (you’ll use this in /ProductGeneration/AdCreative)

  • Prompt recommendations based on the uploaded image

  • A list of recommended presetIds from /ProductGeneration/PresetKeys that best match the uploaded image.

Useful for preparing everything needed for the /ProductGeneration/AdCreative step with a single call.

Endpoint

POST /api/v1/Image/ProductGeneration/Recommendations

Headers

Name
Required
Description

Content-Type

Yes

multipart/form-data

Accept

Yes

application/json

x-api-key

Yes

Your API Key

x-api-secret

Yes

Your API Secret

Form Data Parameters

Name
Type
Required
Description

applicationId

GUID

Yes

ID of the application (API integrator)

userId

GUID

Yes

ID of the user (or internal customer mapping)

productImage

File

Yes

JPG/PNG file up to 12MB

Example Request (cURL)

Example Success Response

Error Responses

Missing Token or Invalid Token

Missing or Invalid File Upload

📸 /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.

🔐 Headers

  • Content-Type: multipart/form-data

  • Accept: application/json

  • x-api-key: your api key

  • x-api-secret: your api secret

🧾 Form Data Parameters

Name
Required
Type
Description

applicationId

✅

string

Application ID

userId

✅

string

User ID

renderKind

✅

int

One of: 0, 1, 2, 4, 8, 16, 31, 32, 64, 128, 256, 512, 992, 1023

productImageAssetId

✅

string

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:

...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

✅ Example Response

GET /ProductGeneration/Download

This endpoint is used to retrieve generated product visuals based on a taskId and imageProductGeneratorProcessId. It supports optional format and resolution flags.

🔗 Endpoint

📥 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

📤 Headers

Key
Value

Accept

application/json

x-api-key

{your_api_key}

x-api-secret

{your_api_secret}

Authorization

Bearer {jwt_token}

📦 Example cURL Request

✅ Response

Returns the image as a file stream or downloadable content. If an error occurs, the following structure may be returned:

📝 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

  • 400 Bad Request – API Key Credits for Application does not exist

  • 400 Bad Request – Validation Error

🧠 Check User Progress

Endpoint: GET /api/v1/Image/ProductGeneration/CheckUserProgress

Description: Check the real-time rendering progress of Product Photoshoot generation requests for a specific user and render process.

URL: https://api.adcreative.ai/api/v1/Image/ProductGeneration/CheckUserProgress?userId=2f1e3c4d-5b6a-4d8f-9c01-e2d3c4b5f6a7&imageProductGeneratorProcessId=60a743a6-c761-4168-9288-40a729dd407e

Authorization: Bearer Token (Required) This request uses the Bearer Token

Headers:

Query Parameters:

  • userId (Required): The user ID of the requester

  • imageProductGeneratorProcessId (Required): ID of the render process you wish to check

🧪 Example Request

✅ Example Response

Notes:

  • renderState value 5 indicates that the generation task is completed.

  • The taskUrls array contains publicly accessible image URLs for each generated product photo.

  • Use the taskId values from this response when calling the Download endpoint.

📊 GET /api/v1/Image/ProductGeneration/CheckApplicationAllProgresses

Checks the progress of all user-level image generations within a specific application.

Endpoint: GET /api/v1/Image/ProductGeneration/CheckApplicationAllProgresses Auth: Bearer Token

🔐 Headers

Key
Value

Accept

application/json

x-api-key

f8a3d2c6e9b1a7d4c5f0e6b3a9d7c2f1

x-api-secret

b7e4c1d9a5f2e8c6d3a9b0f1c7e2d5a3f6b8c9a1...

📥 Params

Key
Description

applicationId

Required

🧪 Example Request

📤 Example Response

This endpoint is ideal for applications managing multiple users and monitoring all ongoing generation jobs across the system.

PreviousAd Text Generation APINextCreative Scoring API (Soon)

Last updated