Image Search
通过图片跨 Shopify 店铺查找商品，可选用关键词收窄。
POST /v1/shopify/image-search仅支持 POST，使用 JSON 请求体。
请求
curl -X POST "https://gateway.apinoa.com/v1/shopify/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')\"}}"参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
image | object | 是 | Base64 image input for visual search; the image is the anchor and query narrows it — the reverse of search. Up to ~6MB of base64; supported types are jpeg, png, webp, gif and avif. |
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. | |
condition | enum | Item condition: new or used. refurbished is refused by name rather than folded into used — the catalog sells new and secondhand, and those are different claims. new used | |
cursor | string | Opaque; comes from the previous response and carries the page index. Shopify pages by cursor rather than by number — this is the only paging knob, and page is refused by name. | |
inStock | boolean | enum | Only listings the marketplace reports as purchasable now. | |
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 text that refines the image — the reverse of search, where the query anchors the result. For example, a sneaker photo with query=wool returns wool sneakers rather than any sneaker of that shape. | |
ratingMin | number 0–5 | Lowest average star rating to return, on the marketplace's own 0-5 scale. | |
region | string | Buyer country as ISO 3166-1 alpha-2; sets availability, shipping and price. |
这些参数及所有响应类型也写在OpenAPI 文档中。
响应
在 data 中返回 SearchResult。 真实响应的节选：数组只保留前几项，长文本已截断。
{
"success": true,
"data": {
"marketplace": "shopify",
"page": {
"index": 1,
"size": 50,
"total": 403
},
"items": [
{
"marketplace": "shopify",
"id": "killcrew.co/flame-high-socks-black-orange",
"attributes": [
{
"name": "Material",
"value": "Cotton blend"
},
{
"name": "Length",
"value": "Crew high"
}
],
"title": "FLAME HIGH SOCKS - BLACK / ORANGE",
"url": "https://killcrew.co/products/flame-high-socks-black-orange?variant=40760148623458",
"price": {
"currency": "USD",
"amount": 15
},
"rating": {
"average": 4.8
},
"seller": {
"id": "killcrew.co",
"name": "Kill Crew",
"url": "https://killcrew.co"
},
"inStock": true,
"imageUrl": "https://cdn.shopify.com/s/files/1/1955/8565/files/FLAMEHIGHSOCKS-BLACK_ORANGE.jpg",
"badges": [],
"promotions": []
}
],
"cursor": "eyJjIjoiZXlKdlptWnpaWFFpT2pVd0xDSjBiM1JoYkY5amIzVnVkQ0k2TkRBekxDSnlaWFIxY201bFpDSTZOVEI5IiwiaSI6MiwiaCI6IjdOa2tvb1l6bjV…",
"facets": []
}
}错误
| 状态 | 代码 | 含义 |
|---|---|---|
| 400 | INVALID_CURSOR | 该 cursor 不是本操作返回的。请不带它重新开始。 |
| 400 | INVALID_PARAMS | 参数缺失、未知或超出范围。消息中会指出是哪一个。 |
| 401 | UNAUTHORIZED | 缺少 x-api-key 请求头，或密钥已吊销或未知。 |
| 402 | INSUFFICIENT_BALANCE | 余额不足以支付本次调用。请在控制台充值。 |
| 429 | MARKETPLACE_SATURATED | 并发调用过多。请等待 Retry-After 秒后重试。 |
| 502 | UPSTREAM_ERROR | 平台返回了无法使用的内容。请退避后重试。 |
全部错误代码见 Errors。失败的调用不计费。
价格
价格 每次调用 $0.001。标价；单日调用超过 1,000 次后单价下调。
说明
- 仅支持 POST。 图片以 base64 形式放在 JSON 请求体中发送。
- 图片是基准，
query用于收窄。 只用一张羊毛运动鞋照片，会返回任何该外形的商品；只用 "wool" 一词，会返回任何羊毛制品；两者结合则返回羊毛运动鞋。 - 图片的 base64 最大约 6 MB，格式为 JPEG、PNG、WebP、GIF 或 AVIF。
- 过滤器和分页与 Search 相同。