> ## Documentation Index
> Fetch the complete documentation index at: https://docs.makelocalads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Amazon listing images

> Write up to nine listing image ideas for a marketplace, then render them.

An Amazon listing has a main image and up to eight supporting images. The API
works like the listing workspace, in two steps:

1. **Ideas**: LocalAds writes a direction for each of up to nine slots, for
   the marketplace you pick. Free.
2. **Images**: render the slots you want, all at once or one at a time. Edit a
   slot's direction first if you like. 2 credits per image.

## Before you start

You need:

* an API key with `amazon_listings:generate`, `amazon_listings:read`, and
  `amazon_listings:update` to edit directions
* a product in LocalAds
* 2 credits per image (18 for a full set of nine)

## 1. Pick a marketplace

```bash theme={null}
curl https://makelocalads.com/api/v1/amazon-marketplaces \
  --header "Authorization: Bearer $LOCALADS_API_KEY"
```

```json theme={null}
{
  "data": [
    { "id": "us", "label": "United States", "domain": "amazon.com" },
    { "id": "uk", "label": "United Kingdom", "domain": "amazon.co.uk" }
  ]
}
```

## 2. Write the ideas

```bash theme={null}
curl --request POST \
  --url https://makelocalads.com/api/v1/amazon-listing-ideas \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
    "marketplace": "us"
  }'
```

The request answers once the ideas are saved, which can take up to a minute,
with `201 Created`:

```json theme={null}
{
  "data": [
    {
      "id": "4d6f8a1c-3e5b-4c7d-9f1a-2b4c6d8e0f1a",
      "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
      "marketplace": "us",
      "position": 0,
      "slot_type": "main",
      "title": "MAIN IMG",
      "summary": "The throw folded on pure white, full product in frame, soft shadow.",
      "creative_id": null,
      "status": "idea",
      "image_url": null,
      "updated_at": "2026-09-25T10:00:00.000Z"
    }
  ]
}
```

Writing ideas again replaces the saved set for that marketplace. A slot that
already has an image keeps it.

## 3. Edit a direction (optional)

```bash theme={null}
curl --request PATCH \
  --url https://makelocalads.com/api/v1/amazon-listing-ideas/4d6f8a1c-3e5b-4c7d-9f1a-2b4c6d8e0f1a \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "summary": "The throw folded on an oak bench, morning light, no props." }'
```

## 4. Render the images

Render every saved idea, or the ones in `idea_ids`. `max_creatives` renders
only the first few, main image first:

```bash theme={null}
curl --request POST \
  --url https://makelocalads.com/api/v1/amazon-listing-images \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: listing-us-3310" \
  --data '{
    "product_id": "a1516a75-9be5-461a-93af-c1896a0a3127",
    "marketplace": "us",
    "max_creatives": 5,
    "max_credits": 10
  }'
```

```javascript theme={null}
const response = await fetch("https://makelocalads.com/api/v1/amazon-listing-images", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LOCALADS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "listing-us-3310",
  },
  body: JSON.stringify({
    product_id: "a1516a75-9be5-461a-93af-c1896a0a3127",
    marketplace: "us",
    max_creatives: 5,
    max_credits: 10,
  }),
});

const batch = await response.json();
```

LocalAds returns `202 Accepted` with the slots it started and
`credits_charged`. Poll `GET /amazon-listing-ideas?product_id=...&marketplace=us`
until each slot's `status` is `completed` or `failed`.

To render or re-render one slot, optionally with a new direction:

```bash theme={null}
curl --request POST \
  --url https://makelocalads.com/api/v1/amazon-listing-ideas/4d6f8a1c-3e5b-4c7d-9f1a-2b4c6d8e0f1a/image \
  --header "Authorization: Bearer $LOCALADS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "summary": "Same shot, but on a linen-covered sofa." }'
```

A slot keeps only its newest image in `image_url`. Earlier images stay in
`GET /creatives?type=amazon_listing`.

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `invalid_request` | An unknown marketplace or field |
| `404` | `product_not_found`, `idea_not_found` | Not available to you |
| `422` | `request_rejected` | No saved idea has a direction to render |
| `422` | `insufficient_credits` | Not enough credits. Nothing was charged |
| `422` | `credit_limit_exceeded` | The batch would cost more than `max_credits` |