---
title: "Visual QA"
method: POST
path: "/v2/visual-qa"
---

# Visual QA

`POST /v2/visual-qa`

## Request

- Base URL: `https://image-api.photoroom.com`
- URL: `https://image-api.photoroom.com/v2/visual-qa`
- Auth: API key in header `x-api-key`

Analyze an image and return a caption, image metadata, and scores for the requested features (see the `features` enum).

Requires an Enterprise plan: requests authenticated with a non-Enterprise API key receive a 403 with a link to contact our sales team.

## Request body `multipart/form-data`

- object
  - `imageFile` string, binary: Image to analyze, as a binary file. Provide exactly one of imageFile or imageUrl.
  - `imageUrl` string, uri: URL of the image to analyze. Provide exactly one of imageFile or imageUrl.
  - `referenceImageFile` string, binary: Reference image (binary) to compare against, required when features includes fashionFidelity or foodFidelity. Provide exactly one of referenceImageFile or referenceImageUrl.
  - `referenceImageUrl` string, uri: URL of the reference image to compare against, required when features includes fashionFidelity or foodFidelity. Provide exactly one of referenceImageFile or referenceImageUrl.
  - `features` string[]: Features to run, as an array or a comma-separated string (e.g. "aiGenerated,text"). If omitted, you still receive the caption and metadata.
  - `clothingItemDetection` boolean: Detect distinct clothing/footwear/accessory items in the image.

## Response `200`

OK

- object
  - `caption` string: A generated caption describing the image. Omitted if no caption could be produced.
  - `clothingItemDetection` object: Distinct clothing, footwear, and accessory items detected in the image. Only present when clothingItemDetection is requested.
    - `items` object[], required: Distinct clothing items, footwear, and accessories detected in the image, each with a short name and a category from a fixed list.
      - `name` string, required: Short, descriptive name of the item (e.g. "black leather jacket"). Plain name only — no bounding boxes — intended for direct use as a text-guided-segmentation prompt.
      - `category` 'top' | 't-shirt' | 'shirt' | 'blouse' | 'sweater' | 'dress' | 'skirt' | 'shorts' | 'trousers' | 'jacket' | 'coat' | 'shoes' | 'accessory' | 'other', required: The clothing category this item was classified into, from a fixed, versioned list (e.g. pumps or sneakers are classified as "shoes").
  - `metadata` object, required: Basic image metadata.
    - `width` number: Image width in pixels.
    - `height` number: Image height in pixels.
    - `format` string: Image format, e.g. "jpeg" or "png".
    - `sizeMB` number: Approximate image size in megabytes.
  - `features` object, required: Requested features and their results; only requested features are present.
    - `aiGenerated` object: Likelihood the image is AI-generated. Scores closer to 1 mean a higher likelihood.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `hate` object: Likelihood the image contains hateful or offensive content such as hate symbols. Scores closer to 1 mean a higher likelihood.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `violence` object: Likelihood the image contains violent content. Scores closer to 1 mean a higher likelihood.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `text` object: Likelihood the image contains artificial (added) text. Scores closer to 1 mean a higher likelihood.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `overallImageQuality` object: Overall image quality (sharpness, blur, contrast, brightness). Scores closer to 1 mean better quality.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `humanElements` object: Likelihood the image contains humans or human elements such as hands or legs. Scores closer to 1 mean a higher likelihood.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `isEcommerceProduct` object: Whether the main subject is a sellable physical product — a consumer good or retail item, food included: score 1 if so, 0 otherwise (e.g. logos, people, landscapes, abstract art).
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `isFoodOrBeverage` object: Whether the main subject is an edible or drinkable item (packaged food, fresh produce, beverages, dishes, snacks): score 1 if so, 0 otherwise. A refinement of isEcommerceProduct — request both when you need food-specific routing.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `cropped` object: Crop-quality assessment and detected subject bounding box.
      - `score` number, required: Crop-quality score. Scores closer to 1 mean a higher likelihood the subject is cropped.
      - `subjectBoundingBox` object, required: Subject location relative to image size (0 to 1). A 0 (xmin/ymin) or 1 (xmax/ymax) means the subject touches that edge and is cropped.
        - `ymin` number, required
        - `ymax` number, required
        - `xmin` number, required
        - `xmax` number, required
    - `shadowCastOverProduct` object: Whether a shadow is cast over the product: score 1 if present, 0 otherwise.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `fashionFidelity` object: Similarity between the image and the reference image (e.g. ghost-mannequin, virtual try-on): scores closer to 1 mean a better match. Requires a reference image.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.
    - `foodFidelity` object: Whether an edited image stays faithful to the reference image: 0 = faithful, 1 = a fidelity issue detected. Requires a reference image.
      - `score` number, required: Score for this feature; see the feature description for its meaning and range.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `500`: Internal Server Error

## Changes

- **2026-11-03** `a9597c56073d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/photoroom/apis/photoroom-api/changes/v2/visual-qa/post.md)

---

[API](https://skmtc.dev/photoroom/apis/photoroom-api.md) - [All operations](https://skmtc.dev/photoroom/apis/photoroom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/photoroom/apis/photoroom-api/revisions/a9597c56073d?raw)