## 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](/content/api-docs/human-quickstart/index.html) 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:

- **Listing Builder** (`POST /v1/api/listing_builder`): a complete listing from an ASIN, main image plus gallery.
- **A+ Content** (`POST /v1/api/a_plus`): Amazon A+ modules (Basic, Premium, Premium Mobile).
- **Clone** (`POST /v1/api/scale`): replicate a reference visual identity onto a new ASIN.

And one strategy endpoint:

- **Creative Strategy** (`POST /v1/api/creative_strategy`): the strategy behind the visuals, as JSON. Personas, reviews, needs and positioning. Costs 5 credits.

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

- `pk_live_` keys run the real pipeline, consume credits, and take about two minutes.
- `pk_test_` keys return a mock response instantly and never consume credits. 
- A missing or invalid key returns `401` with error code `UNAUTHORIZED`.

## 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:

- Poll `GET /v1/api/jobs/{job_id}` about every 5 seconds. **Job polling is not rate limited.**
- If a job fails, credits are automatically refunded. Individual images can fail inside an otherwise-completed job (partial failure); the job still reports `completed`.

## 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`