Image Search
通过图片查找 Amazon 商品。每个匹配项都与关键词搜索返回的商品相同。
POST /v1/amazon/image-search仅支持 POST，使用 JSON 请求体。
参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
image | object | 是 | The picture to search by: {contentType, data} with data base64-encoded. POST only — a base64 image is tens of kilobytes and a URL caps out around 8 KB. |
categoryId | string | Narrow to one category, by the marketplace's own id. Opaque and per-marketplace; take it from Product.category[].id or from a result's facets. | |
page | integer | 1-based page number over the visual matches, about 48 per page; each page is charged separately. No pageSize and no cursor. | |
priceMax | number ≥ 0 | Highest price to return, in decimal major units. | |
priceMin | number ≥ 0 | Lowest price to return, in decimal major units. | |
query | string | Optional words that narrow the visual matches, e.g. the product type. Supplying it is usually much more precise. | |
ratingMin | number | 4 only. Amazon's rating filter offers exactly one threshold, "4 Stars & Up"; any other value is a 400 rather than a silently different search. Not available on amazon.fr (region=FR). | |
region | enum | Which Amazon marketplace to query, by buyer country: US, CA, MX, BR, FR, IT, ES, NL, SE, TR, AE, SA, IN, JP, SG, AU. Defaults to US. Prices come back in that marketplace's own currency (JP in JPY, FR in EUR). US CA MX BR FR IT ES NL SE TR AE SA IN JP SG AU | |
sort | enum | Result ordering: best_match, price_asc, price_desc, newly_listed or avg_review. Defaults to best_match, Amazon's own relevance ordering. best_match price_asc price_desc newly_listed avg_review |
请求
curl -X POST "https://gateway.apinoa.com/v1/amazon/image-search" \
-H "x-api-key: $APINOA_API_KEY" \
-H "content-type: application/json" \
-d "{\"image\": {\"contentType\": \"image/jpeg\", \"data\": \"$(base64 < photo.jpg | tr -d '\n')\"}}"响应
在 data 中返回 SearchResult。 真实响应的节选：数组只保留前几项，长文本已截断。
{
"success": true,
"data": {
"marketplace": "amazon",
"page": {
"index": 1,
"size": 48,
"total": 90
},
"items": [
{
"marketplace": "amazon",
"id": "B07F3FFTMK",
"title": "Alvada Mens Merino Wool Crew Socks Thermal and Warm Socks for Winter Work Hiking Running 3 Pairs",
"attributes": [],
"price": {
"currency": "USD",
"amount": 13.49
},
"url": "https://www.amazon.com/dp/B07F3FFTMK",
"imageUrl": "https://m.media-amazon.com/images/I/91aOC3G1W6L.jpg",
"category": [
{
"name": "Women's Hiking Socks"
}
],
"variantCount": 24,
"listPrice": {
"currency": "USD",
"amount": 14.99
},
"unitPrice": {
"price": {
"currency": "USD",
"amount": 4.5
},
"unit": "count"
},
"rating": {
"average": 4.5,
"count": 37581
},
"salesLabel": "10K+ bought in past month",
"salesCount": 10000,
"delivery": {
"estimate": "Non-members get FREE delivery Thu, Oct 29 on $35 of items shipped by Amazon",
"free": true,
"minimumOrder": {
"currency": "USD",
"amount": 35
},
"minDays": 5,
"maxDays": 5
},
"shippingOptions": [
{
"estimate": "Non-members get FREE delivery Thu, Oct 29 on $35 of items shipped by Amazon",
"free": true,
"minimumOrder": {
"currency": "USD",
"amount": 35
},
"minDays": 5,
"maxDays": 5
},
{
"estimate": "Join Prime to get FREE delivery Tomorrow, Oct 25",
"free": true,
"membership": "Prime",
"minDays": 1,
"maxDays": 1
}
],
"badges": [
"Best Seller in Women's Hiking Socks",
"Limited time deal"
],
"promotions": [],
"matchScore": 0.70708364
}
]
}
}错误
| 状态 | 代码 | 含义 |
|---|---|---|
| 400 | INVALID_PARAMS | 参数缺失、未知或超出范围。消息中会指出是哪一个。 |
| 401 | UNAUTHORIZED | 缺少 x-api-key 请求头，或密钥已吊销或未知。 |
| 402 | INSUFFICIENT_BALANCE | 余额不足以支付本次调用。请在控制台充值。 |
| 429 | MARKETPLACE_SATURATED | 并发调用过多。请等待 Retry-After 秒后重试。 |
| 502 | UPSTREAM_ERROR | 平台返回了无法使用的内容。请退避后重试。 |
全部错误代码见 Errors。失败的调用不计费。
价格
价格 每次调用 $0.001，每多一次调用加 $0.001——最多再加 1 次，合计最多 $0.002。图片有匹配时 2 个单位；没有匹配时 1 个单位。标价；单日调用超过 1,000 次后单价下调。
说明
- 仅支持 POST。 base64 图片有几十 KB，而查询字符串的上限约为 8 KB。
query用于收窄图片结果。 图片决定结果的主题，文字用于收窄。一张手办照片单独搜索返回 48 个匹配，加上query: "plush"后返回 22 个。价格、评分、类目过滤器和sort的作用与搜索相同。- JPEG、PNG 或 GIF。 WebP 和 HEIC 会以 400 被拒绝，请先转换格式。
- 无匹配不是错误。 Amazon 无法识别任何内容的图片会返回空的
items，计 1 个单位；有匹配时计 2 个单位。 - 分页。 每页约 48 个匹配；持续请求下一个
page，直到items返回为空。每一页都单独计费。