---
title: "Image Search"
description: "사진으로 Amazon 상품을 찾습니다. 각 결과는 키워드 검색이 돌려주는 것과 같은 항목입니다."
---

```http
POST /v1/amazon/image-search
```

`POST` 전용이며 JSON 본문으로 보냅니다.

## 파라미터

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `image` | object | yes | 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` |

## 요청

```bash tab="cURL"
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')\"}}"
```

```js tab="JavaScript"
import { readFile } from "node:fs/promises";

const data = (await readFile("photo.jpg")).toString("base64");
const res = await fetch("https://gateway.apinoa.com/v1/amazon/image-search", {
  method: "POST",
  headers: { "x-api-key": process.env.APINOA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({ image: { contentType: "image/jpeg", data } }),
});
const { success, data: result, error } = await res.json();
```

```python tab="Python"
import base64
import os

import requests

with open("photo.jpg", "rb") as f:
    data = base64.b64encode(f.read()).decode()

res = requests.post(
    "https://gateway.apinoa.com/v1/amazon/image-search",
    json={"image": {"contentType": "image/jpeg", "data": data}},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
body = res.json()
```

## 응답

`data`에 [`SearchResult`](/docs/api-reference/marketplaces/response-schema#searchresult)를 돌려줍니다. 실제 응답을 줄인 것입니다. 배열은 앞쪽 항목만 남기고 긴 텍스트는 잘랐습니다.

```json
{
  "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](/docs/errors)에 있습니다. 실패한 호출은 과금되지 않습니다.

## 가격

**Price** $0.001 per call, plus $0.001 for each extra call it makes — at most 1 more, so $0.002 in total. 사진이 매칭되면 2단위, 아무것도 매칭되지 않으면 1단위입니다. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day.

## 참고

- **POST 전용입니다.** base64 이미지는 수십 킬로바이트이고, 쿼리 문자열은 약 8 KB가 한계입니다.
- **`query`는 이미지를 좁힙니다.** 결과가 무엇에 관한 것인지는 이미지가 정하고, 단어는 이를 좁힙니다. 피규어 사진 하나로는 48개가, `query: "plush"`를 함께 넘기면 22개가 나왔습니다. 가격·평점·카테고리 필터와 `sort`는 검색과 똑같이 적용됩니다.
- **JPEG, PNG 또는 GIF.** WebP와 HEIC는 400으로 거부되므로 먼저 변환하세요.
- **결과가 없어도 오류가 아닙니다.** Amazon이 아무것도 인식하지 못한 이미지는 빈 `items`를 돌려주며 1단위가 청구되고, 결과가 있으면 2단위입니다.
- **페이지네이션.** 페이지당 약 48개입니다. `items`가 비어서 돌아올 때까지 다음 `page`를 요청하세요. 페이지마다 청구됩니다.