# Product images

Reads, uploads and deletes images for a catalog product. All routes require an API key with the `catalog` scope; uploads and deletes require a write-enabled key.

The methods return only the product's native images: its detail picture, preview picture, and `MORE_PHOTO` gallery items. Files stored in other custom File properties (`propertyNNN`) are not included.

These routes use the shared product ID space for simple products, SKUs, variations and services.

Bitrix24 API: `catalog.productImage.list`, `catalog.productImage.get`, `catalog.productImage.add`, `catalog.productImage.delete`
Scope: `catalog`

## Safe handling of the image address

Treat `detailUrl` as untrusted input. The API validates only the URL shape and returns it without normalization. Do not make a server-side HTTP request to this address: doing so creates a server-side request forgery (SSRF) risk. A path beginning with `/` is relative to the Bitrix24 account origin. For a user interface, pass the address to a safe client-side component instead of downloading it through your backend.

The `downloadUrl` download link is not included in the response because it may contain a webhook path and secret. The API neither proxies nor downloads the file. A `detailUrl` containing a webhook path is also rejected.

## Operations

- [Upload product image](./images-create.md) — `POST /v1/catalog-products/:productId/images`
- [List product images](./images-list.md) — `GET /v1/catalog-products/:productId/images`
- [Get product image](./images-get.md) — `GET /v1/catalog-products/:productId/images/:imageId`
- [Delete product image](./images-delete.md) — `DELETE /v1/catalog-products/:productId/images/:imageId`

## Key fields

| Field | Description |
|-------|-------------|
| `id` | Image ID. List: [`GET /v1/catalog-products/:productId/images`](./images-list.md) |
| `productId` | ID of the product that owns the image. List: [`GET /v1/catalog-products`](/docs/entities/catalog-products/list) |
| `type` | Image type: `DETAIL_PICTURE` — detail picture, `PREVIEW_PICTURE` — preview picture, `MORE_PHOTO` — gallery image |
| `name` | File name |
| `createTime` | Creation time in ISO 8601 format with a UTC offset, or `null` |
| `detailUrl` | Image address — a path starting with `/` relative to the Bitrix24 account origin, or an absolute `http`/`https` URL. Treat it as untrusted input — see "Safe handling of the image address" above |

A response example with these fields: [Get product image](./images-get.md).

## Typical scenario

1. Find the product and its `id`: [`GET /v1/catalog-products?filter[iblockId]=25`](/docs/entities/catalog-products/list).
2. Upload an image: [`POST /v1/catalog-products/:productId/images`](./images-create.md). The response carries the `id` of the new image.
3. View all product images: [`GET /v1/catalog-products/:productId/images`](./images-list.md).
4. Get a single image: [`GET /v1/catalog-products/:productId/images/:imageId`](./images-get.md).
5. Delete the image: [`DELETE /v1/catalog-products/:productId/images/:imageId`](./images-delete.md).

## Limits

| Limit | Value |
|-------|-------|
| Upload request body | Up to 40 MiB. A larger body is rejected with `413 PAYLOAD_TOO_LARGE` |
| List pagination | None: [`GET /v1/catalog-products/:productId/images`](./images-list.md) returns all product images in one call |
| Detail and preview pictures | One of each per product. Uploading `DETAIL_PICTURE` or `PREVIEW_PICTURE` again replaces the previous one, while `MORE_PHOTO` adds an image to the gallery |
| Request rate | Shared limit of the Vibecode API — [Limits and optimization](/docs/optimization) |

## See also

- [Catalog products](/docs/entities/catalog-products)
- [Get catalog product](/docs/entities/catalog-products/get)
- [Catalog prices](/docs/entities/catalog-prices)