Agent quickstart — Pixii API

Introduction

This is a single-page, self-contained reference for calling the Pixii API from an AI agent or automated tool. It consolidates the only information you need to make a correct call: the base URL, authentication, the async job pattern, each endpoint with its required parameters and allowed values, the defaults to assume when a user is vague, and the full error reference.

If you are a human getting started, read the Human quickstart instead.

What is the Pixii API?

Pixii generates platform-optimized Amazon and e-commerce product visuals from an ASIN. You submit a product, Pixii analyzes it, and it returns production-ready images for Amazon, Shopify, TikTok Shop, or Walmart.

Three generation endpoints:

And one strategy endpoint:

All four are asynchronous: they return a job_id, and you poll the Jobs API for the result.

Base URL

https://api.pixii.ai

HTTPS only (plain HTTP is rejected). Every endpoint path is prefixed with /v1/api.

Authentication

Send your API key as a Bearer token in the Authorization header on every request:

Authorization: Bearer pk_live_xxxxxxxxxxxx

Async job pattern

Every generation endpoint returns a job_id immediately with status: "pending". You then poll the Jobs API until the job finishes.

  1. Submit the job. You get back { job_id, status: "pending" }.
  2. Poll GET /v1/api/jobs/{job_id} every ~5 seconds.
  3. Stop when status is completed (read output) or failed (read error_code).

Statuses:

pending: Job received and queued processing: Job is actively running completed: Finished successfully, output is ready failed: Job failed, see error_code

What an agent must know:

Rate limiting

Rate limits are enforced at the organization level (all API keys in an org share one bucket) and apply to job submission endpoints only. Job status polling is not rate limited.

Window Limit
Per minute 10 requests
Per day 500 requests

Every job-submission response includes X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day, and X-RateLimit-Remaining-Day headers.

Listing Builder

Generate a complete, platform-optimized listing (main image plus gallery) from an ASIN.

POST /v1/api/listing_builder
Parameter Type Required Description
asin string Required Amazon Standard Identification Number. Minimum 5 characters.
country_code string Required Target marketplace. Default US if the user did not specify.
listing_type enum Required Type of listing. Default amazon_listing if the user did not specify.
main_image_url string Optional Product's main image URL. Must be publicly accessible.
other_image_urls string[] Optional Additional image URLs. Minimum 1 item if provided. Must be publicly accessible.
include_creative_strategy boolean Optional Also return the creative strategy in the completed job output. Default false.
effort enum Optional How much creative freedom the generator gets: creative (default) or reliable.

listing_type accepts:

amazon_listing: Full Amazon listing, main image plus gallery (default) amazon_main_images: Amazon main images only amazon_mobile_listing: Optimized for Amazon mobile shopify_listing: Shopify product page visuals tiktok_listing: TikTok Shop optimized visuals walmart_listing: Walmart product page visuals

A+ Content

Generate Amazon A+ modules (Basic, Premium, Premium Mobile) from an ASIN.

POST /v1/api/a_plus
Parameter Type Required Description
asin string Required Amazon Standard Identification Number.
country_code string Required Target marketplace. Default US if the user did not specify.
types enum[] Required One or more A+ variants to generate. 1 to 10 unique values.
main_image_url string Optional Product's main image URL. Must be publicly accessible.
other_image_urls string[] Optional Additional image URLs. Minimum 1 item if provided.
user_prompt string Optional Natural-language guidance. Cannot be empty if provided.

Clone

Replicate a reference visual identity onto a target ASIN.

POST /v1/api/scale
Parameter Type Required Description
asin string Required Amazon Standard Identification Number.
country_code string Required Target marketplace. Default US if the user did not specify.
scale_mode enum Required How Clone generates the new assets. Default catalog when the user just says "clone this" or "scale this".
main_image_input string Optional Product's main image URL. Must be publicly accessible.
other_images_input string[] Optional Additional image URLs. Minimum 1 item if provided.
user_prompt string Optional Natural-language guidance. Cannot be empty if provided. Required for scale_mode "language" (specify the target language here).
items ScaleItem[] Required Reference assets to clone from. Minimum 1 item.

Creative Strategy

Return the creative strategy for an ASIN as JSON: who buys it, what reviewers say, what they need, and how to position it. Use this when the user asks for strategy, personas, positioning or messaging rather than images.

POST /v1/api/creative_strategy
Parameter Type Required Description
asin string Required Amazon Standard Identification Number. Minimum 5 characters.
country_code string Required Target marketplace. Default US if the user did not specify.
force_new boolean Optional Regenerate even if a strategy already exists. Default false.

Recommended defaults

Use the user’s value if they gave one. Otherwise assume these. (The API marks these fields as required; these are the sensible defaults an agent should send when the user was not specific.)

country_code defaults to US. Supported ISO 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