Create listing

Generate a complete product listing from an ASIN. Main image plus full gallery, in one job.

Generate a complete product listing from an ASIN. Pixii analyzes the product and produces a full set of visuals, main image plus gallery, designed for your target platform and marketplace.

This endpoint costs 70 credits per listing. Visuals that fail to generate are refunded individually.

This is an async endpoint. It returns a job_id immediately. Use the Jobs API to poll for the result.

Endpoint

POST /v2/api/create_listing

Request body

Parameter	Type	Required	Description
`brand_id`	`number`	Optional	The brand to work in. Take it from Brands. Defaults to your default brand.
`product`	`object`	Required	The product to design for. See product below.
`listing_type`	`enum`	Required	Type of listing. See listing types below.
`effort`	`enum`	Optional	How much creative freedom the generator gets. See effort below. Defaults to `Creative`.
`user_prompt`	`string`	Optional	Creative direction in your own words, up to 1000 characters. For example a scene, a mood, an audience or a claim to feature.
`include_creative_strategy`	`boolean`	Optional	Include the creative strategy in the completed job output. Defaults to `false`. No extra credits.

Product

The product object identifies the product to design for. Pass an ASIN with its marketplace, or the product_id of a product Pixii already knows (every completed job returns one in its output). The asin field also takes a product page URL: an Amazon product page of any marketplace (shortlinks included), which is read as its ASIN and marketplace, a Walmart product page (walmart.com or walmart.ca), which is read as its item ID and marketplace, or a Shopify product page. A Walmart item ID also goes in asin; its country_code is US (walmart.com, the default) or CA (walmart.ca), and any other marketplace fails with VALIDATION_ERROR. create_anything, scale and download_visuals accept these same forms. A product_id that is not in your account fails the job with PRODUCT_NOT_FOUND.

Parameter	Type	Required	Description
`asin`	`string`	Optional	Amazon Standard Identification Number, Walmart item ID, or an Amazon, Walmart or Shopify product page URL. `country_code` is required with a bare ASIN; a Walmart item ID takes `US` (default) or `CA`.
`country_code`	`string`	Optional	Marketplace of the ASIN. See supported marketplaces below.
`product_id`	`string`	Optional	Pixii product ID. Use instead of `asin` and `country_code`.
`main_image`	`string`	Optional	Your own main image for the product, as a public image URL or base64 bytes (PNG, JPEG or WebP, up to 10 MB). Only with `asin`.
`other_images`	`string[]`	Optional	Up to 4 additional product images, URLs or base64 bytes. Requires `main_image`.

Listing types

The listing_type field accepts one of the following values:

Amazon Listing Full Amazon product listing, main image plus gallery

Shopify Listing Shopify product page visuals

TikTok Shop Listing TikTok Shop optimized visuals

Walmart Listing Walmart product page visuals

Amazon Mobile Listing Optimized for Amazon mobile display

Amazon Main Images Amazon main images only

Effort

The optional effort field controls how far the generator may stray from your product photos:

Creative The generator may compose new angles and scenes for your product (default)

Reliable Every visual stays on an angle your product photos already show

Supported marketplaces

The country_code field accepts any of the following ISO country codes:

AE AU BE BR CA CN DE EG ES FR GB IE IN IT JP MX NL PL SA SE SG TR UK US ZA

Creative strategy

Set include_creative_strategy to true and the completed job’s output carries a creative_strategy object alongside the visuals. It is the same analysis the Creative strategy API returns, at no extra cost, because this job already produced it.

Response

A successful request returns 200 with a job id. The job runs in the background, so use the Jobs API to retrieve the result.

Field	Type	Description
`job_id`	string	Unique identifier for the job. Use this to poll for results.
`job_type`	string	Always `create_listing` for this endpoint.
`brand_id`	number	The brand the job runs in.
`session_id`	string	The Pixii session that will hold the visuals, the same value the job output returns.
`status`	string	Initial status. Always `pending` on submission.
`created_at`	string	ISO 8601 timestamp of when the job was created.
`credit_cost`	number	Credits charged for this job.
`remaining_credits`	number	Credits remaining on your account after this request was accepted.

Submitting the same product again while a job for it is still running returns the running job instead of starting a second one.

Job output

When the job completes, output contains:

Field	Type	Description
`product`	object	`product_id`, `asin` and `country_code` of the product.
`session_id`	string	The Pixii session that holds these visuals.
`listing_type`	string	The listing type that was generated.
`campaign_ads`	array	One entry per generated visual, the main image first. See campaign ads.
`creative_strategy`	object	Only when `include_creative_strategy` is `true`.

Errors

Code	HTTP	Description
`VALIDATION_ERROR`	400	One or more request parameters are invalid.
`INVALID_IMAGE`	400	An image is not a public URL or valid base64.
`NO_ACTIVE_BRAND`	400	No active brand found for your organization.
`BRAND_NOT_FOUND`	404	No active brand with this `brand_id` in your organization.
`UNAUTHORIZED`	401	Missing or invalid API key.
`INSUFFICIENT_CREDITS`	402	Not enough credits to process this request.
`RATE_LIMIT_MINUTE_EXCEEDED`	429	Too many requests in the current minute window.
`RATE_LIMIT_DAY_EXCEEDED`	429	Daily request limit reached.
`INTERNAL_ERROR`	500	An unexpected error occurred.
`SERVICE_UNAVAILABLE`	503	Service is temporarily unavailable.

See the errors reference for the full list and how to handle each one.

Request

curl -X POST https://api.pixii.ai/v2/api/create_listing \
-H "Authorization: Bearer pk_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
  "product": {
    "asin": "B08N5WRWNW",
    "country_code": "US",
    "main_image": "https://example.com/main.jpg",
    "other_images": ["https://example.com/angle.jpg"]
  },
  "listing_type": "Amazon Listing",
  "effort": "Reliable",
  "user_prompt": "Warm kitchen scenes, highlight the non-stick coating",
  "include_creative_strategy": true
}'

import requests

response = requests.post(
"https://api.pixii.ai/v2/api/create_listing",
headers={
"Authorization": "Bearer pk_live_xxxxxxxxxxxx",
"Content-Type": "application/json",
},
json={
"product": {
"asin": "B08N5WRWNW",
"country_code": "US",
"main_image": "https://example.com/main.jpg",
"other_images": ["https://example.com/angle.jpg"],
},
"listing_type": "Amazon Listing",
"effort": "Reliable",
"user_prompt": "Warm kitchen scenes, highlight the non-stick coating",
"include_creative_strategy": True,
},
)

Response json

{

"success": true,
"data": {
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"job_type": "create_listing",
"brand_id": 42,
"session_id": "1762085000000-k3j9qx",
"status": "pending",
"created_at": "2026-11-02T12:00:00Z",
"credit_cost": 70,
"remaining_credits": 2430
},
"error": null
}

Completed job output json

{

"product": {
"product_id": "6655f1c2a3b4c5d6e7f80912",
"asin": "B08N5WRWNW",
"country_code": "US"
},
"session_id": "1762085000000-k3j9qx",
"listing_type": "Amazon Listing",
"campaign_ads": [
{
"id": "6655f2d4a3b4c5d6e7f80a01",
"preview": "https://storage.googleapis.com/...signed...",
"video_url": null,
"platform": "Amazon",
"asset_type": "Main Image",
"deliverable_number": 1,
"grid_order": 1,
"status": "completed"
},
{
"id": "6655f2d4a3b4c5d6e7f80a02",
"preview": null,
"video_url": null,
"platform": "Amazon",
"asset_type": "Product Photo",
"deliverable_number": 2,
"grid_order": 2,
"status": "failed"
}
],
"creative_strategy": { "...": "..." }
}

Error response json

{

"success": false,
"data": null,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"detail": "product: country_code is required with asin"
}
}

See the errors reference for the full list of error codes and how to handle them.