Vision Identify

POST /v3/vision/identify

Legacy path: POST /api/v3/vision/identify (same behavior).

Upload or link an image to identify a luxury item. The API analyzes the image and returns matching catalog rows in the same shape as Search catalog.

Request

Image URL

curl -X POST https://api.pricehero.ai/v3/vision/identify \
  -H "Authorization: Bearer ph_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-bag.jpg",
    "includes": ["taxonomy", "pricing"]
  }'

From base64

curl -X POST https://api.pricehero.ai/v3/vision/identify \
  -H "Authorization: Bearer ph_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64": "data:image/jpeg;base64,/9j/4AAQ...",
    "includes": ["taxonomy"]
  }'

Body parameters

Parameter	Type	Required	Description
`url`	string	One of these	Public image URL
`base64`	string	One of these	Base64 image (`data:image/...;base64,...` or raw); JPEG/PNG/WebP
`includes`	string[]	—	`taxonomy`, `pricing` only (default `["taxonomy"]`)

Send at least one of url or base64. If both are present, url is used (same as the API).

Successful responses include includes, resolved_taxonomy (from the first hit), pagination fields, credits_used, and data — same item shape as catalog search (id, name, popularity, images, thumbnails; attributes and variant.fields when taxonomy is in includes; variants only when the item is a product; variant.pricing when pricing is requested).

{
  "success": true,
  "results": 3,
  "total_results": 3,
  "page": 0,
  "total_pages": 1,
  "credits_used": 10,
  "includes": ["taxonomy", "pricing"],
  "resolved_taxonomy": { "node": "product", "level": 3 },
  "data": [
    {
      "id": "product_K9xLpQ2vZrT7mN4cHs8YbEwUdA1FgR6jX0qP",
      "name": "Louis Vuitton Speedy 30",
      "confidence": 0.93,
      "attributes": [
        {
          "field": "brand",
          "id": "brand_R7xVn3LpQ2sK8mTzH5YwE9aU4FbG1JdC6uN",
          "name": "Louis Vuitton"
        }
      ],
      "popularity": 85,
      "images": ["https://cdn.pricehero.ai/img/variant_Z4mQx8TnLpR2sV7cHk9YwE5aU1FbG6JdC3uN.jpg"],
      "thumbnails": [
        "https://cdn.pricehero.ai/thumb/variant_Z4mQx8TnLpR2sV7cHk9YwE5aU1FbG6JdC3uN.jpg"
      ],
      "variants": [
        {
          "id": "variant_Z4mQx8TnLpR2sV7cHk9YwE5aU1FbG6JdC3uN",
          "fields": [{ "field": "size", "name": "Medium" }],
          "images": [
            "https://cdn.pricehero.ai/img/variant_Z4mQx8TnLpR2sV7cHk9YwE5aU1FbG6JdC3uN.jpg"
          ],
          "thumbnails": [
            "https://cdn.pricehero.ai/thumb/variant_Z4mQx8TnLpR2sV7cHk9YwE5aU1FbG6JdC3uN.jpg"
          ],
          "popularity": 92,
          "pricing": {
            "market_estimates": [
              {
                "A": 1250,
                "B": 1050,
                "C": 800,
                "D": 550,
                "currency": "usd",
                "region": "NA",
                "source": "google_shopping",
                "estimated_at": "2026-03-15T00:00:00Z",
                "confidence": null
              }
            ],
            "historical_estimates": [{ "region": "NA", "url": "https://example.com/history.json" }],
            "pricing_data": [{ "region": "NA", "url": "https://example.com/pricing.json" }]
          }
        }
      ]
    }
  ]
}

Image guidelines

Clear, well-lit photos; front or main angle; logos and hardware visible if possible.
Formats: JPEG, PNG, WebP. Large images are compressed server-side for the vision model.

Credits

See Credits. Vision is billed together with any requested data modules (taxonomy, pricing).