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

# Visual QA v3

`POST /v3/visual-qa`

## Request

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

Analyze an image and return the results of the requested features (see the `features` enum).

The `mainGarmentColor` and `mainGarmentCategory` features classify the main garment against a taxonomy you supply per request, in `colorTaxonomy` and `categoryTaxonomy` respectively. Each feature and its taxonomy must be sent together — one without the other is a 400. Both classifications ride on the same model call as `clothingItemDetection`, so asking for any combination of the three costs a single call.

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` union, required: Features to run, as an array or a comma-separated string (e.g. "caption,aiGenerated"). Only the requested features are computed and returned; at least one is required.
    - string: Comma-separated list of features, e.g. "caption,aiGenerated".
    - string[]
  - `colorTaxonomy` string: JSON array of the colour taxonomy to classify the main garment against: 1 to 1000 entries of { code, name?, hex }, where hex is a 6-digit colour with or without the leading "#". Required when features includes mainGarmentColor, and rejected without it. Codes must be unique and are returned verbatim.
  - `categoryTaxonomy` string: JSON array of the category taxonomy to classify the main garment against, flattened and linked by parentCode: 1 to 2000 nodes of { code, name, parentCode? }. A node with no parentCode is a root. Required when features includes mainGarmentCategory, and rejected without it. Codes must be unique and are returned verbatim.

## Response `200`

OK

- object
  - `caption` string: A generated caption describing the image. Only present when the caption feature is requested.
  - `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").
  - `mainGarment` object: The garment mainGarmentColor and mainGarmentCategory describe. Only present when at least one of those two features is requested and a garment was found. It can be present without either classification, when the garment matched no entry of the supplied taxonomies.
    - `description` string, required: Short name of the garment that was classified (e.g. "rust blouse"), naming which item mainGarmentColor and mainGarmentCategory describe.
    - `type` 'top' | 't-shirt' | 'shirt' | 'blouse' | 'sweater' | 'dress' | 'skirt' | 'shorts' | 'trousers' | 'jacket' | 'coat' | 'shoes' | 'accessory' | 'other', required: Photoroom's own fixed category for that garment, from the same list as clothingItemDetection items and independent of the supplied categoryTaxonomy.
  - `mainGarmentColor` object: The colorTaxonomy entry matched to the main garment. Only present when the mainGarmentColor feature is requested and a garment was matched.
    - `code` string, required: Code of the matched colorTaxonomy entry, returned verbatim.
    - `name` string: Name of the matched entry, present only if the supplied entry carried one.
    - `hex` string, required: Hex colour of the matched entry.
  - `mainGarmentCategory` object: The categoryTaxonomy node matched to the main garment, with its full ancestry. Only present when the mainGarmentCategory feature is requested and a garment was matched.
    - `code` string, required: Code of the matched categoryTaxonomy node, returned verbatim.
    - `name` string, required: Name of the matched node.
    - `path` object[], required: Root-first ancestry of the matched node, ending with the node itself. Accuracy is highest at the shallower levels, so read the depth your catalogue actually distinguishes rather than always taking the leaf.
      - `code` string, required: Code of this ancestor, as supplied in categoryTaxonomy.
      - `name` string, required: Name of this ancestor, as supplied in categoryTaxonomy.
  - `metadata` object: Basic image metadata. Only present when the metadata feature is requested.
    - `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.
  - `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 — returned when neither or both of imageFile / imageUrl are given, when no feature or an unknown feature is requested, when a reference image is missing for or supplied outside fashionFidelity / foodFidelity, when a taxonomy is not valid JSON or breaks its size or entry-shape bounds, or when mainGarmentColor / mainGarmentCategory and its taxonomy are not sent together.
- `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/v3/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)