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

# Image Search: Upload Image

> Image Upload API endpoint that accepts a binary image and returns an image ID you can pass into the Image Search endpoint for visual product lookup.

## Authorization

<ParamField header="X-Storefront-Access-Token" type="string" required>
  Token-based authentication header in the form of `<YOUR_LAYERS_TOKEN>`.
</ParamField>

## Headers

<ParamField header="Content-Type" type="string" default="multipart/form-data" required />

<ParamField header="Accept" type="string" default="application/json" required />

## Body

<ParamField body="image" type="file" required>
  Image file to upload. Supported formats: JPEG, JPG, PNG, WebP, HEIC, and HEIF. Maximum file size: 15MB (15,360 KB).
</ParamField>

<ParamField body="crop_x" type="integer">
  X-coordinate (in pixels) of the top-left corner of the crop region. Must be `0` or greater. When provided, all four crop parameters (`crop_x`, `crop_y`, `crop_width`, `crop_height`) are required.
</ParamField>

<ParamField body="crop_y" type="integer">
  Y-coordinate (in pixels) of the top-left corner of the crop region. Must be `0` or greater.
</ParamField>

<ParamField body="crop_width" type="integer">
  Width (in pixels) of the crop region. Must be `1` or greater.
</ParamField>

<ParamField body="crop_height" type="integer">
  Height (in pixels) of the crop region. Must be `1` or greater.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Status of the upload operation. Returns "success" on successful upload.
</ResponseField>

<ResponseField name="imageId" type="string">
  Unique UUID identifier for the uploaded image. Use this ID in the Image Search API to perform visual searches.
</ResponseField>

## Usage

The Image Upload endpoint enables a two-step process for visual search:

1. **Upload the image** using this endpoint to receive an `imageId`
2. **Search with the image** using the `imageId` in the [Image Search API](/api-reference/search-image)

This approach offers several advantages:

* **Better performance**: Avoids repeated base64 encoding/decoding
* **Caching**: Processed image embeddings are cached for faster subsequent searches
* **Reduced payload size**: Use lightweight UUID instead of large base64 strings

## Error responses

<ResponseField name="errors" type="object">
  Validation errors returned when the request fails validation.
</ResponseField>

Common validation errors:

* **File required**: No image file provided
* **Invalid file type**: File format not supported (must be JPEG, JPG, PNG, WebP, HEIC, or HEIF)
* **File too large**: Image exceeds 15MB size limit
* **Missing crop parameters**: All four crop parameters must be provided together

<ResponseExample>
  ```json Response theme={null}
  {
      "status": "success",
      "imageId": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json Error Response theme={null}
  {
      "message": "The given data was invalid.",
      "errors": {
          "image": [
              "The image field is required."
          ]
      }
  }
  ```
</ResponseExample>