Ecommerce Image API

Use the public API to generate ecommerce product images from another service. Requests are authenticated with an API key and consume credits from the account that owns that key.

Authentication

Create an API key from Settings > API Keys. The API key feature must be enabled with NEXT_PUBLIC_ENABLE_API_KEYS=true.

Send the key with either header:

Authorization: Bearer YOUR_API_KEY

or:

x-api-key: YOUR_API_KEY

Create a Job

POST /api/v1/ecommerce-images/jobs

The request body is multipart/form-data.

Field	Type	Required	Description
`payload`	JSON string	Yes	Generation input, model, and resolution.
`referenceImages`	File[]	Yes	Product reference images. Repeat this form field to send multiple files. JPEG, PNG, and WebP are supported.

curl -X POST https://lbanai.com/api/v1/ecommerce-images/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'payload={"input":{"productName":"Travel Mug","brandName":"Acme","category":"Drinkware","market":"global","platforms":["amazon"],"style":"clean_white","outputs":["main_image"],"variantCount":1,"detailPageMode":"auto","sellingPoints":"Leak-proof lid, stainless steel body","mustKeep":"Keep the original mug shape and logo","avoid":"No extra accessories","textOverlay":"","authorizationConfirmed":true},"model":"gpt-image-2.5-flare","resolution":"1k"}' \
  -F "referenceImages=@product.png"

Reference Images

referenceImages provide the main source for product appearance, material, color, structure, and packaging. At least one reference image is required, or the API returns 400.

Item	Description
Form field	`referenceImages`. For multiple images, repeat the field, for example `-F "referenceImages=@front.png" -F "referenceImages=@side.png"`.
Compatibility field	`referenceImage` is also accepted for a single image, but new integrations should use `referenceImages`.
Formats	JPEG, PNG, WebP.
File size	Up to 4 MB per image.
Count limit	Depends on `model`: GPT Image 2.5 supports up to 16; the other listed models support up to 10.
Rights confirmation	`payload.input.authorizationConfirmed` must be `true`, confirming that you have rights to use the reference image, brand elements, copy, and IP.
Generation effect	The system prioritizes preserving the product body, color, structure, logo, and packaging. Use `mustKeep` for required details and `avoid` for unwanted elements.

Successful responses include:

Field	Description
`jobId`	The generated job id. Use it to query job details.
`status`	`completed`, `partial_failed`, `failed`, or `blocked`.
`assets`	Generated asset results, including image URLs when successful.
`consumedCredits`	Credits charged for successful assets.
`complianceReport`	Compliance check result for the request.

Payload

payload is a JSON string with this shape:

{
  "input": {
    "productName": "Travel Mug",
    "brandName": "Acme",
    "category": "Drinkware",
    "market": "global",
    "platforms": ["amazon"],
    "style": "clean_white",
    "outputs": ["main_image"],
    "variantCount": 1,
    "detailPageMode": "auto",
    "sellingPoints": "Leak-proof lid, stainless steel body",
    "mustKeep": "Keep the original mug shape and logo",
    "avoid": "No extra accessories",
    "textOverlay": "",
    "authorizationConfirmed": true
  },
  "model": "gpt-image-2.5-flare",
  "resolution": "1k"
}

Input Fields

Field	Type	Required	Limits / values
`productName`	string	Yes	2-120 characters.
`brandName`	string	No	Up to 80 characters. Use `""` if not needed.
`category`	string	Yes	2-120 characters.
`market`	enum	Yes	See markets below.
`platforms`	enum[]	Yes	1-4 platforms. See platforms below.
`style`	enum	Yes	See styles below.
`outputs`	enum[]	Yes	One or more output types.
`variantCount`	number	Yes	Integer from 1 to 5.
`detailPageMode`	enum	No	`auto`, `technical`, `standard`, `kids`. Defaults to `auto`.
`sellingPoints`	string	No	Up to 800 characters.
`mustKeep`	string	No	Up to 500 characters.
`avoid`	string	No	Up to 500 characters.
`textOverlay`	string	No	Up to 240 characters.
`authorizationConfirmed`	boolean	Yes	Must be `true` when you have rights to use the reference image.

Enum Values

`market`

The target market influences language, visual taste, compliance hints, and the default ecommerce context used in the prompt.

Value	UI label	When to use
`north_america`	North America	For the US, Canada, and similar retail contexts with clear, trustworthy product presentation.
`europe`	Europe	For restrained, standards-aware, quality-focused European retail visuals.
`southeast_asia`	Southeast Asia	For Shopee, Lazada, and Southeast Asia cross-border use cases with bright mobile-first visuals.
`southeast_asia_chinese`	Southeast Asia Chinese market	For Chinese-language Southeast Asia audiences, holidays, or Chinese lifestyle contexts.
`mainland_china`	Mainland China	For Taobao, JD.com, Pinduoduo, Douyin, Kuaishou, Xiaohongshu, and other mainland China platforms.
`japan`	Japan	For clean, detail-focused, low-noise, reliable Japanese marketplace visuals.
`korea`	Korea	For trend-forward Korean beauty, fashion, and lifestyle contexts.
`middle_east`	Middle East	For Middle East markets where conservative presentation and local cultural sensitivity matter.
`brazil`	Brazil	For brighter, warmer, more lifestyle-oriented Brazilian consumer contexts.
`global`	Global	For generic cross-border usage when no single market should dominate.

`platforms`

Platforms control aspect ratio, background, product framing, text overlay rules, and banned content. The API accepts 1-4 platforms; each selected platform produces assets using that platform's rules.

Value	UI label	Aspect	Background / scene	Text rule	Product rule
`amazon`	Amazon	`1:1`	Pure white `#FFFFFF`	No text, logo, watermark, or price.	Centered product, at least 85% of the frame.
`shopee`	Shopee	`1:1`	White or lifestyle scene	Text overlays up to about 20%; no misleading pricing.	Product fills at least 70%; mobile thumbnail friendly.
`tiktok_shop`	TikTok Shop	`1:1`	Authentic lifestyle scene	Text overlays up to about 15%.	Product visible in a real-use context.
`kuaishou`	Kuaishou	`1:1`	Real-use scene or bright marketplace background	Short benefit text up to about 20%; no false claims.	Practical, trustworthy, clear in mobile feeds.
`douyin`	Douyin	`1:1`	Trend-forward lifestyle scene	Short punchy text up to about 15%; no exaggerated promises.	Product must be instantly recognizable in-feed.
`xiaohongshu`	Xiaohongshu	`3:4`	Clean lifestyle note scene	Light editorial annotations; avoid hard-sell claims.	Natural styling with a premium discovery feel.
`taobao`	Taobao	`1:1`	White, light solid, or polished lifestyle scene	Promotional text up to about 20%; no misleading pricing.	Product fills at least 70%; clear main-image readability.
`pinduoduo`	Pinduoduo	`1:1`	Bright clean value-focused background	Benefit text up to about 20%; no exaggerated claims.	Clear product with a practical value-for-money feel.
`jd`	JD.com	`1:1`	Clean white or premium light studio background	Limited functional text only; no exaggerated claims.	Centered, sharp, quality-focused product presentation.
`lazada`	Lazada	`1:1`	Clean pure white	No store watermark on main images; limited functional text only.	Product fills at least 80%; clear and professional.
`aliexpress`	AliExpress	`1:1`	Pure white or light gray solid background	No text, watermark, logo overlay, or price tag for normal main images.	Clean global marketplace product image.
`temu`	Temu	`1:1`	Bright white or light solid background	Text overlays up to about 20%; no exaggerated claims.	Clear product with an affordable-premium feel.
`shein`	SHEIN	`3:4`	White or simple fashion scene	Text overlays up to about 15%.	Young fashion marketplace framing; avoid busy backgrounds.

`style`

Use auto to let the system recommend a style from category, or pass a fixed style for more control.

Value	UI label	Best for	Common platforms
`auto`	Auto	Automatically routes electronics/tools to clean white, beauty/home/fashion to lifestyle, kids/stationery to illustrated, and premium goods to minimal editorial.	All platforms
`clean_white`	Clean White	Standard marketplace main images with pure studio background, crisp edges, and minimal distraction.	Amazon, AliExpress, Temu, Lazada, Shopee, Taobao, Pinduoduo, JD.com
`lifestyle`	Lifestyle	Authentic settings, warm natural light, and a polished real-use commercial scene.	Shopee, TikTok Shop, Kuaishou, Douyin, Xiaohongshu, Taobao, SHEIN, Lazada
`premium_minimal`	Premium Minimal	High-ticket goods, gifts, jewelry, beauty, or products that need whitespace, subtle shadows, and low-saturation polish.	Amazon, AliExpress, Shopee, Xiaohongshu, Taobao, JD.com, Lazada, SHEIN
`bold_vibrant`	Bold & Vibrant	Saturated, high-contrast mobile marketplace and promotion visuals.	Shopee, Temu, TikTok Shop, Kuaishou, Douyin, Taobao, Pinduoduo, SHEIN
`illustrated`	Illustrated	Kids, stationery, gifts, and creative goods with friendly illustration accents around the real product.	Shopee, TikTok Shop, Douyin, Xiaohongshu
`ugc_rush`	UGC Rush	Authentic, slightly imperfect social commerce visuals for short-video selling.	TikTok Shop, Kuaishou, Douyin, SHEIN

`outputs`

Value	UI label	Description
`main_image`	Main image	Platform-specific product main image, usually the strictest output for background, aspect ratio, and product size.
`variant`	Variant	Alternative compositions or scenes for the same product. Quantity is controlled by `variantCount`.
`detail_page`	Detail page	Detail-page or selling-point image that also uses `detailPageMode`.

`detailPageMode`

Value	Description
`auto`	Let the system choose the detail-page treatment. Good for most products.
`technical`	Technical/specification layout for electronics, tools, appliances, or feature-heavy products.
`standard`	Standard benefits layout for daily goods, home, beauty, fashion, and general products.
`kids`	Family-friendly layout for kidswear, toys, baby products, stationery, and similar categories.

Models

Model	Resolutions	Reference image limit
`nano-banana-2`	`0.5k`, `1k`, `2k`, `4k`	Up to 14 images
`nano-banana-2-ext`	`0.5k`, `1k`, `2k`, `4k`	Up to 14 images
`gpt-image-2.5-flare`	`1k`, `2k`, `4k`	Up to 16 images
`gpt-image-2.5-sunburst`	`1k`, `2k`, `4k`	Up to 16 images
`seedream-5-0-flash`	`1k`, `1.5k`, `2k`	Up to 10 images
`seedream-5-0-pro`	`1k`, `1.5k`, `2k`	Up to 10 images
`seedream-5-0-lite`	`2k`, `3k`, `4k`	Up to 10 images
`flux-2-pro`	`1mp`, `2mp`, `3mp`, `4mp`	Up to 8 images

The supported aspect ratios are validated together with the selected resolution. Omit resolution to use the model's configured default. All active models use the APIMart image API. Nano Banana 2 supports auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 5:4, 4:5, 21:9, 1:4, 4:1, 1:8, and 8:1. GPT Image 2.5 supports auto, 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21, 3:1, and 1:3. Seedream 5.0 supports auto, 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, and 21:9. FLUX.2 Pro supports 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, and 9:16 (no auto).

Get a Job

GET /api/v1/ecommerce-images/jobs/:id

curl https://lbanai.com/api/v1/ecommerce-images/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Only jobs owned by the API key account are visible.

Errors

Status	Meaning
`400`	Invalid payload or form data.
`401`	Missing, invalid, or disabled API key.
`402`	The account does not have enough credits.
`404`	Job not found for this account.
`422`	Compliance checks blocked the job.
`500`	Generation or storage failed.

Ecommerce Image API

Use the public API to generate ecommerce product images from another service. Requests are authenticated with an API key and consume credits from the account that owns that key.

Authentication

Create an API key from Settings > API Keys. The API key feature must be enabled with NEXT_PUBLIC_ENABLE_API_KEYS=true.

Send the key with either header:

Authorization: Bearer YOUR_API_KEY

or:

x-api-key: YOUR_API_KEY

Create a Job

POST /api/v1/ecommerce-images/jobs

The request body is multipart/form-data.

Field	Type	Required	Description
`payload`	JSON string	Yes	Generation input, model, and resolution.
`referenceImages`	File[]	Yes	Product reference images. Repeat this form field to send multiple files. JPEG, PNG, and WebP are supported.

curl -X POST https://lbanai.com/api/v1/ecommerce-images/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F 'payload={"input":{"productName":"Travel Mug","brandName":"Acme","category":"Drinkware","market":"global","platforms":["amazon"],"style":"clean_white","outputs":["main_image"],"variantCount":1,"detailPageMode":"auto","sellingPoints":"Leak-proof lid, stainless steel body","mustKeep":"Keep the original mug shape and logo","avoid":"No extra accessories","textOverlay":"","authorizationConfirmed":true},"model":"gpt-image-2.5-flare","resolution":"1k"}' \
  -F "referenceImages=@product.png"

Reference Images

referenceImages provide the main source for product appearance, material, color, structure, and packaging. At least one reference image is required, or the API returns 400.

Item	Description
Form field	`referenceImages`. For multiple images, repeat the field, for example `-F "referenceImages=@front.png" -F "referenceImages=@side.png"`.
Compatibility field	`referenceImage` is also accepted for a single image, but new integrations should use `referenceImages`.
Formats	JPEG, PNG, WebP.
File size	Up to 4 MB per image.
Count limit	Depends on `model`: GPT Image 2.5 supports up to 16; the other listed models support up to 10.
Rights confirmation	`payload.input.authorizationConfirmed` must be `true`, confirming that you have rights to use the reference image, brand elements, copy, and IP.
Generation effect	The system prioritizes preserving the product body, color, structure, logo, and packaging. Use `mustKeep` for required details and `avoid` for unwanted elements.

Successful responses include:

Field	Description
`jobId`	The generated job id. Use it to query job details.
`status`	`completed`, `partial_failed`, `failed`, or `blocked`.
`assets`	Generated asset results, including image URLs when successful.
`consumedCredits`	Credits charged for successful assets.
`complianceReport`	Compliance check result for the request.

Payload

payload is a JSON string with this shape:

{
  "input": {
    "productName": "Travel Mug",
    "brandName": "Acme",
    "category": "Drinkware",
    "market": "global",
    "platforms": ["amazon"],
    "style": "clean_white",
    "outputs": ["main_image"],
    "variantCount": 1,
    "detailPageMode": "auto",
    "sellingPoints": "Leak-proof lid, stainless steel body",
    "mustKeep": "Keep the original mug shape and logo",
    "avoid": "No extra accessories",
    "textOverlay": "",
    "authorizationConfirmed": true
  },
  "model": "gpt-image-2.5-flare",
  "resolution": "1k"
}

Input Fields

Field	Type	Required	Limits / values
`productName`	string	Yes	2-120 characters.
`brandName`	string	No	Up to 80 characters. Use `""` if not needed.
`category`	string	Yes	2-120 characters.
`market`	enum	Yes	See markets below.
`platforms`	enum[]	Yes	1-4 platforms. See platforms below.
`style`	enum	Yes	See styles below.
`outputs`	enum[]	Yes	One or more output types.
`variantCount`	number	Yes	Integer from 1 to 5.
`detailPageMode`	enum	No	`auto`, `technical`, `standard`, `kids`. Defaults to `auto`.
`sellingPoints`	string	No	Up to 800 characters.
`mustKeep`	string	No	Up to 500 characters.
`avoid`	string	No	Up to 500 characters.
`textOverlay`	string	No	Up to 240 characters.
`authorizationConfirmed`	boolean	Yes	Must be `true` when you have rights to use the reference image.

Enum Values

`market`

The target market influences language, visual taste, compliance hints, and the default ecommerce context used in the prompt.

Value	UI label	When to use
`north_america`	North America	For the US, Canada, and similar retail contexts with clear, trustworthy product presentation.
`europe`	Europe	For restrained, standards-aware, quality-focused European retail visuals.
`southeast_asia`	Southeast Asia	For Shopee, Lazada, and Southeast Asia cross-border use cases with bright mobile-first visuals.
`southeast_asia_chinese`	Southeast Asia Chinese market	For Chinese-language Southeast Asia audiences, holidays, or Chinese lifestyle contexts.
`mainland_china`	Mainland China	For Taobao, JD.com, Pinduoduo, Douyin, Kuaishou, Xiaohongshu, and other mainland China platforms.
`japan`	Japan	For clean, detail-focused, low-noise, reliable Japanese marketplace visuals.
`korea`	Korea	For trend-forward Korean beauty, fashion, and lifestyle contexts.
`middle_east`	Middle East	For Middle East markets where conservative presentation and local cultural sensitivity matter.
`brazil`	Brazil	For brighter, warmer, more lifestyle-oriented Brazilian consumer contexts.
`global`	Global	For generic cross-border usage when no single market should dominate.

`platforms`

Platforms control aspect ratio, background, product framing, text overlay rules, and banned content. The API accepts 1-4 platforms; each selected platform produces assets using that platform's rules.

Value	UI label	Aspect	Background / scene	Text rule	Product rule
`amazon`	Amazon	`1:1`	Pure white `#FFFFFF`	No text, logo, watermark, or price.	Centered product, at least 85% of the frame.
`shopee`	Shopee	`1:1`	White or lifestyle scene	Text overlays up to about 20%; no misleading pricing.	Product fills at least 70%; mobile thumbnail friendly.
`tiktok_shop`	TikTok Shop	`1:1`	Authentic lifestyle scene	Text overlays up to about 15%.	Product visible in a real-use context.
`kuaishou`	Kuaishou	`1:1`	Real-use scene or bright marketplace background	Short benefit text up to about 20%; no false claims.	Practical, trustworthy, clear in mobile feeds.
`douyin`	Douyin	`1:1`	Trend-forward lifestyle scene	Short punchy text up to about 15%; no exaggerated promises.	Product must be instantly recognizable in-feed.
`xiaohongshu`	Xiaohongshu	`3:4`	Clean lifestyle note scene	Light editorial annotations; avoid hard-sell claims.	Natural styling with a premium discovery feel.
`taobao`	Taobao	`1:1`	White, light solid, or polished lifestyle scene	Promotional text up to about 20%; no misleading pricing.	Product fills at least 70%; clear main-image readability.
`pinduoduo`	Pinduoduo	`1:1`	Bright clean value-focused background	Benefit text up to about 20%; no exaggerated claims.	Clear product with a practical value-for-money feel.
`jd`	JD.com	`1:1`	Clean white or premium light studio background	Limited functional text only; no exaggerated claims.	Centered, sharp, quality-focused product presentation.
`lazada`	Lazada	`1:1`	Clean pure white	No store watermark on main images; limited functional text only.	Product fills at least 80%; clear and professional.
`aliexpress`	AliExpress	`1:1`	Pure white or light gray solid background	No text, watermark, logo overlay, or price tag for normal main images.	Clean global marketplace product image.
`temu`	Temu	`1:1`	Bright white or light solid background	Text overlays up to about 20%; no exaggerated claims.	Clear product with an affordable-premium feel.
`shein`	SHEIN	`3:4`	White or simple fashion scene	Text overlays up to about 15%.	Young fashion marketplace framing; avoid busy backgrounds.

`style`

Use auto to let the system recommend a style from category, or pass a fixed style for more control.

Value	UI label	Best for	Common platforms
`auto`	Auto	Automatically routes electronics/tools to clean white, beauty/home/fashion to lifestyle, kids/stationery to illustrated, and premium goods to minimal editorial.	All platforms
`clean_white`	Clean White	Standard marketplace main images with pure studio background, crisp edges, and minimal distraction.	Amazon, AliExpress, Temu, Lazada, Shopee, Taobao, Pinduoduo, JD.com
`lifestyle`	Lifestyle	Authentic settings, warm natural light, and a polished real-use commercial scene.	Shopee, TikTok Shop, Kuaishou, Douyin, Xiaohongshu, Taobao, SHEIN, Lazada
`premium_minimal`	Premium Minimal	High-ticket goods, gifts, jewelry, beauty, or products that need whitespace, subtle shadows, and low-saturation polish.	Amazon, AliExpress, Shopee, Xiaohongshu, Taobao, JD.com, Lazada, SHEIN
`bold_vibrant`	Bold & Vibrant	Saturated, high-contrast mobile marketplace and promotion visuals.	Shopee, Temu, TikTok Shop, Kuaishou, Douyin, Taobao, Pinduoduo, SHEIN
`illustrated`	Illustrated	Kids, stationery, gifts, and creative goods with friendly illustration accents around the real product.	Shopee, TikTok Shop, Douyin, Xiaohongshu
`ugc_rush`	UGC Rush	Authentic, slightly imperfect social commerce visuals for short-video selling.	TikTok Shop, Kuaishou, Douyin, SHEIN

`outputs`

Value	UI label	Description
`main_image`	Main image	Platform-specific product main image, usually the strictest output for background, aspect ratio, and product size.
`variant`	Variant	Alternative compositions or scenes for the same product. Quantity is controlled by `variantCount`.
`detail_page`	Detail page	Detail-page or selling-point image that also uses `detailPageMode`.

`detailPageMode`

Value	Description
`auto`	Let the system choose the detail-page treatment. Good for most products.
`technical`	Technical/specification layout for electronics, tools, appliances, or feature-heavy products.
`standard`	Standard benefits layout for daily goods, home, beauty, fashion, and general products.
`kids`	Family-friendly layout for kidswear, toys, baby products, stationery, and similar categories.

Models

Model	Resolutions	Reference image limit
`nano-banana-2`	`0.5k`, `1k`, `2k`, `4k`	Up to 14 images
`nano-banana-2-ext`	`0.5k`, `1k`, `2k`, `4k`	Up to 14 images
`gpt-image-2.5-flare`	`1k`, `2k`, `4k`	Up to 16 images
`gpt-image-2.5-sunburst`	`1k`, `2k`, `4k`	Up to 16 images
`seedream-5-0-flash`	`1k`, `1.5k`, `2k`	Up to 10 images
`seedream-5-0-pro`	`1k`, `1.5k`, `2k`	Up to 10 images
`seedream-5-0-lite`	`2k`, `3k`, `4k`	Up to 10 images
`flux-2-pro`	`1mp`, `2mp`, `3mp`, `4mp`	Up to 8 images

Get a Job

GET /api/v1/ecommerce-images/jobs/:id

curl https://lbanai.com/api/v1/ecommerce-images/jobs/JOB_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Only jobs owned by the API key account are visible.

Errors

Status	Meaning
`400`	Invalid payload or form data.
`401`	Missing, invalid, or disabled API key.
`402`	The account does not have enough credits.
`404`	Job not found for this account.
`422`	Compliance checks blocked the job.
`500`	Generation or storage failed.

Ecommerce Image API

Ecommerce Image API

Authentication

Create a Job

Reference Images

Payload

Input Fields

Enum Values

`market`

`platforms`

`style`

`outputs`

`detailPageMode`

Models

Get a Job

Errors

Table of Contents

Ecommerce Image API

Ecommerce Image API

Authentication

Create a Job

Reference Images

Payload

Input Fields

Enum Values

`market`

`platforms`

`style`

`outputs`

`detailPageMode`

Models

Get a Job

Errors

Table of Contents