Image Search

Search for similar products on supported marketplaces (Taobao, 1688) using an image URL.

POSThttps://open.hiobuy.com/api/client/third-purchase/image/query

If your deployment uses a different base URL, replace `https://open.hiobuy.com` accordingly.

Request headers

Name	Required	Type	Description
`X-Uuid`	Yes	string	Merchant UUID assigned to your account
`Language`	No	string	Locale for product titles and attributes. Default: `zh_CN`. See supported locales.

Supported locales

Marketplace	Code	Locale
Taobao	`zh_CN`	Chinese
Taobao	`en_US`	English
Taobao	`vi_VN`	Vietnamese
1688	`zh_CN`	Chinese
1688	`en_US`	English
1688	`ko_KR`	Korean
1688	`ja`	Japanese
1688	`ru_RU`	Russian
1688	`vi_VN`	Vietnamese
1688	`es_ES`	Spanish
1688	`ar`	Arabic

Request body

Name	Required	Type	Description
`img`	Yes	string	Publicly accessible image URL
`platform`	Yes	string	Marketplace code: `taobao` (Taobao), `1688` (1688.com)
`use_platform`	No	string	Whether to use 1688 platform-native response fields. `0` = off, `1` = on. 1688 only. See 1688 API reference.
`filter`	No	array	Search filters (1688 only). See 1688 filter reference.

Example request

{
  "img": "https://example.com/sample-product.jpg",
  "platform": "1688"
}

Sample response

{
  "ret": 1,
  "msg": "success",
  "data": {
    "api_type": "taobao",
    "items": {
      "item": [
        {
          "detail_url": "https://detail.1688.com/offer/808368541552.html",
          "title_cn": "性感蕾丝低胸睡衣…",
          "title": "Sexy Lace Low-cut Pajamas…",
          "pic_url": "https://cbu01.alicdn.com/O1CN01Z797hC1jEpv3AKmQ8_!!2216007294517-0-cib.jpg",
          "price": "21.80",
          "sales": 415,
          "num_iid": 808368541552,
          "seller_nick": "object_id%40808368541552…",
          "tag_percent": "19%",
          "trace_info": "object_id%40808368541552…",
          "top_category_id": 312,
          "category_id": 122450002
        }
      ],
      "total_results": 1000
    }
  }
}

The `item` array may contain many results; only one entry is shown above.

Response fields

Top level

Name	Type	Description
`ret`	number	Status code. `1` indicates success
`msg`	string	Status message
`data`	object	Response body

`data.items.item[]`

Name	Type	Description
`detail_url`	string	Product detail page URL
`num_iid`	integer	Marketplace product ID
`pic_url`	string	Main image URL
`price`	string	Unit price
`sales`	integer	Units sold (cumulative)
`title_cn`	string	Chinese title
`title`	string	Localized title (per `Language` header)
`seller_nick`	string	Seller shop name (image search may return a trace ID; use shop-nick when you have `shop_id`)
`tags`	array	Product tags
`quantity`	integer	Available stock
`tag_percent`	string	Match confidence (e.g. `19%`)
`trace_info`	string	Platform trace token for follow-up requests
`top_category_id`	integer	Top-level category ID
`category_id`	integer	Leaf category ID

Pagination

Name	Type	Description
`data.items.total_results`	integer	Total number of matched products