PHphotoroom

Visual QA v3

Changed on

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.

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

Request body multipart/form-data

imageFilestring binary

Image to analyze, as a binary file. Provide exactly one of imageFile or imageUrl.

imageUrlstring uri

URL of the image to analyze. Provide exactly one of imageFile or imageUrl.

referenceImageFilestring binary

Reference image (binary) to compare against, required when features includes fashionFidelity or foodFidelity. Provide exactly one of referenceImageFile or referenceImageUrl.

referenceImageUrlstring uri

URL of the reference image to compare against, required when features includes fashionFidelity or foodFidelity. Provide exactly one of referenceImageFile or referenceImageUrl.

colorTaxonomystring

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.

categoryTaxonomystring

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.

Example request

{
  "imageUrl": "https://example.com/image.jpg",
  "referenceImageUrl": "https://example.com/reference.jpg",
  "colorTaxonomy": "[{\"code\":\"COLOR-027\",\"name\":\"Navy\",\"hex\":\"#002062\"}]",
  "categoryTaxonomy": "[{\"code\":\"TOPS\",\"name\":\"Tops\"},{\"code\":\"TEE\",\"name\":\"T-Shirts\",\"parentCode\":\"TOPS\"}]"
}

Response

OK

captionstring

A generated caption describing the image. Only present when the caption feature is requested.

Example response

{
  "caption": "Three gold rings with blue stones on a marble surface.",
  "mainGarment": {
    "description": "rust blouse"
  },
  "mainGarmentColor": {
    "code": "COLOR-042",
    "name": "Brick",
    "hex": "#AF4942"
  }
}

Changes