Agent quickstart

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. Every endpoint here has a dedicated reference page too, linked from the sidebar.

Rule of thumb for every parameter below: if the user gave a value, use theirs. If they did not, use the recommended default.

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, or TikTok Shop.

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).
• Scale / Clone (POST /v1/api/scale): replicate a reference visual identity across new ASINs. Users may call this “clone this”.

All three 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. Use them to validate integration wiring.
• A missing or invalid key returns 401 with error code UNAUTHORIZED.

Async job pattern

Every generation endpoint (Listing Builder, A+ Content, Scale / Clone) 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:

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 failed image carries an error and refunded credits, the job still reports completed.
• Completed results and their signed image URLs are valid for 7 days. Download and store images before then.

{
"success": true,
"data": {
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_type": "Listing Builder",
  "status": "pending",
  "created_at": "2026-04-07T12:00:00Z"
},
"error": null
}

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.

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

When a limit is exceeded, Pixii returns 429 with a Retry-After header (seconds to wait) and error code RATE_LIMIT_MINUTE_EXCEEDED or RATE_LIMIT_DAY_EXCEEDED. The body also carries retry_after. Wait that many seconds; do not guess a fixed delay. Back off before X-RateLimit-Remaining-Minute reaches zero.

Listing Builder

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

POST /v1/api/listing_builder

listing_type accepts:

{
"asin": "B08N5WRWNW",
"country_code": "US",
"listing_type": "amazon_listing"
}

A+ Content

Generate Amazon A+ modules (Basic, Premium, Premium Mobile) from an ASIN. Each requested variant produces a composite preview plus its individual module images.

POST /v1/api/a_plus

types accepts one or more of:

Total credit cost is the sum of the per-type costs. Failed variants are auto-refunded. On completion, output.ads holds one entry per requested type, each with type, preview (composite URL, valid 7 days), modules (individual image URLs), and error (null on success).

{
"asin": "B08XBGZ4R6",
"country_code": "US",
"types": [
  "A+ Premium Full Image (4 modules)",
  "A+ Premium Mobile Full Image"
]
}

Scale / Clone

Replicate a reference visual identity onto a target ASIN. Users often call this “clone this” or “scale this”; both mean this endpoint.

POST /v1/api/scale

scale_mode accepts:

Each entry in items (a ScaleItem) requires:

Valid platform and asset_type combinations (an unsupported combination returns VALIDATION_ERROR):

{
"asin": "B08N5WRWNW",
"country_code": "US",
"scale_mode": "catalog",
"items": [
  {
    "preview_url": "https://example.com/preview.png",
    "platform": "Amazon",
    "asset_type": "Product Photo"
  }
]
}

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

listing_type (Listing Builder) defaults to amazon_listing.

A+ types, pick based on how specific the user was:

In short: premium defaults to the Full Image 4-module variant (not 6), basic defaults to separate modules, and premium mobile defaults to its Full Image. Only override when the user names an exact variant.

scale_mode (Scale / Clone) defaults to catalog when the user just says “clone this” or “scale this”.

Retrieval and usage endpoints

These are GET requests and (except where noted) return results synchronously.

Poll a job, the core of the async pattern:

GET /v1/api/jobs/{job_id}

Returns the job envelope: id, job_type, status, created_at, started_at, completed_at, credit_cost, credits_refunded, output (null until completed), error_code (null unless failed). Not rate limited.

List jobs for an ASIN:

GET /v1/api/jobs?asin={asin}

asin is required (5 to 15 characters). Paginated (page, limit, limit defaults to 20).

Check remaining credits:

GET /v1/api/usage

Returns credits.remaining.

Error reference

Every error returns a consistent envelope:

{
"success": false,
"error": {
  "code": "VALIDATION_ERROR",
  "message": "Invalid request parameters",
  "detail": "asin: ASIN should be minimum 5 characters long"
}
}

code is machine-readable (switch on it). message is human-readable. detail is present on validation and rate-limit errors. Rate-limit errors add retry_after (seconds).

API errors (returned as a non-2xx HTTP response):

Job errors, returned inside a successful 200 job payload (no HTTP error). They appear as the job’s top-level error_code when the whole job fails, or as ads[].error.code when a single image fails inside a completed job:

For the full human-oriented reference, see the Errors page.