# Images

### How to send images

There are two ways to deliver images. Both can be used for the same product.

1. **As a URL in the product** (recommended). Put a public image URL in an image
   attribute when you create or update a product:

   ```json
   "values": {
     "image_default": [ { "data": "https://cdn.example.com/products/tshirt-001-black-front.jpg", "locale": null } ],
     "image_1": [ { "data": "https://cdn.example.com/products/tshirt-001-black-back.jpg", "locale": null } ]
   }
   ```

   The URL is checked straight away; an invalid URL is answered with `422`. The image
   itself is downloaded **later**, in the background, and then reviewed by Winkelstraat
   before it appears on the product. A successful response therefore does not mean the
   image was accepted, and a failed download is not reported back through the API.
2. **As a separate upload** with
   `POST /api/rest/v1/retailer/media-files`,
   either as a file or as a URL. This call downloads or stores the image immediately and
   reports download problems in its response.

### Image attributes

* `image_default`: the main image. It must always show the **front** of the item.
* `image_1`, `image_2`, …: additional images. `GET /api/rest/v1/retailer/attributes`
  lists all attributes of type `pim_catalog_image`.

Images belong to the product group (`parent`): all sizes share the same images.
Sending an empty value (`"data": null`) removes the image.

### Content requirements

* **File format:** JPG, PNG or WebP. Image URLs should end in `.jpg`, `.png` or
  `.webp`. A query string after the extension (for example `.jpg?v=2`) is accepted,
  but we advise against it.
* **Resolution:** we advise a minimum of 1000 × 1000 pixels.
* **Sharpness:** photos must stay sharp when zoomed in.
* **Background:** preferably white; light grey is also accepted. Dark backgrounds are
  rejected.
* **Photography:** only professional studio photography is accepted.
* **Main image:** always the front of the item, preferably a packshot or on a
  mannequin. A model photo is also allowed.
* **Model photos:** cropping between the nose and the lips is preferred. If needed,
  Winkelstraat can also do this during editing.
* **Additional images:** a photo of the back of the item is preferred. Detail shots are
  required for all items.
* **Rejected:** photos of samples or sketches, lifestyle images, and photos containing
  text (unless the text gives relevant product information).

### Technical requirements for image URLs

* The URL must be a valid, publicly reachable `http` or `https` URL. No login, cookies
  or IP allow-listing.
* The server must respond within 10 seconds and deliver the complete image within 30
  seconds, with a `2xx` status code.
* The response must contain an image file. HTML pages, empty files and unknown file
  types are rejected with `Image type is not supported`.
* For images sent as a URL in the product, a temporary problem (timeout, `408`, `429` or
  `5xx`) is retried up to 3 times in total. Other `4xx` responses are not retried.