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

# Product image uploads

> Upload image files straight into a product's or variant's gallery.

`POST /api/v1/products/{productId}/images` stores an image file and adds it to the product's gallery. It requires `catalog:write`. To use images that are already online, send their URLs in `images` on `PATCH /api/v1/products/{productId}` instead.

## Upload an image

Send the file as `multipart/form-data` in a part named `file`:

```bash theme={null}
curl -sS -X POST "https://omnicommerce.sg/api/v1/products/$PRODUCT_ID/images" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -F "file=@./front.jpg" \
  -F "position=0"
```

| Field | Description |
| - | - |
| `file` | Required. JPEG, PNG, WebP, AVIF, or HEIC up to 8 MB. WebP, AVIF, and HEIC are stored as JPEG. |
| `position` | Zero-based place in the gallery. `0` makes it the main image. Defaults to the end of the gallery. |

`productId` can be a variant UUID to set a variant's own image.

The response is `201` with the stored image and the gallery in order:

```json theme={null}
{
  "ok": true,
  "data": {
    "image": { "url": "https://…/front.jpg", "position": 0 },
    "images": [
      { "url": "https://…/front.jpg", "position": 0 },
      { "url": "https://…/side.jpg", "position": 1 }
    ]
  }
}
```

The upload changes the OmniCommerce product and sends a `product.updated` webhook. Marketplaces get the new gallery the next time you publish: `POST /api/v1/products/{productId}/publish`.

## SDK and CLI

```ts theme={null}
import { readFile } from "node:fs/promises";

await client.products.uploadImage({
  productId,
  file: new File([await readFile("front.jpg")], "front.jpg", {
    type: "image/jpeg",
  }),
  position: 0,
});
```

```python theme={null}
with open("front.jpg", "rb") as file:
    client.products.upload_image(product_id=product_id, file=file, position=0)
```

```bash theme={null}
omni products upload-image --product-id "$PRODUCT_ID" --file ./front.jpg
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.