---
title: "시작하기"
description: "API 키를 만들고, 첫 호출을 보내고, 모든 엔드포인트에 공통인 규칙을 익힙니다."
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt)

## 빠른 시작

### 1. 계정 만들기

[apinoa.com](https://apinoa.com)에서 가입하고 이메일 주소를 인증합니다. 카드는 필요하지 않습니다.

### 2. 크레딧 충전

호출은 선불 잔액에서 [가격 페이지의 요율](/pricing)로 과금됩니다. 고를 요금제는 없습니다.
**대시보드 > 잔액**에서 남은 금액을 확인하고 충전합니다. 먼저 평가해 보려면 대시보드의 무료 크레딧 카드에서
무료 크레딧을 신청하세요. 무료 크레딧은 계정당 모두 합쳐 **$1**까지이며, 3단계의 $0.10도 여기에 포함됩니다.

### 3. API 키 만들기

가장 빠른 방법은 터미널입니다. 프로젝트 디렉터리에서 실행하세요.

```bash
npx apinoa-mcp login
```

열리는 페이지에서 apinoa에 로그인하고(계정이 없으면 새로 만들고), 터미널에 표시된 코드를 입력해 승인하면
키가 `.env`에 `APINOA_API_KEY`로 저장됩니다. 이 방법이나 [호스팅 MCP 서버](/docs/sdks#호스팅-설치-없이) 로그인으로
처음 받는 키에는 **$0.10 평가용 크레딧**이 지급됩니다(계정당 한 번). 자세한 내용은
[인증](/docs/authentication#키-발급)에 있습니다.

또는 **대시보드 > API 키**에서 키를 만듭니다. 키는 생성할 때 **한 번만** 표시되므로 바로 저장하세요.

```bash
export APINOA_API_KEY="myapp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
```

키 하나로 모든 API를 씁니다. 이 문서의 예제는 키를 환경 변수 `APINOA_API_KEY`에서 읽습니다. 위처럼 `export`하거나,
`npx apinoa-mcp login`이 저장한 `.env`를 불러오세요.

### 4. 첫 호출 보내기

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const params = new URLSearchParams({ query: "wool socks" });
const res = await fetch(`https://gateway.apinoa.com/v1/walmart/search?${params}`, {
  headers: { "x-api-key": process.env.APINOA_API_KEY },
});
const { success, data, error } = await res.json();
console.log(success ? data.items[0] : error);
```

```python tab="Python"
import os

import requests

res = requests.get(
    "https://gateway.apinoa.com/v1/walmart/search",
    params={"query": "wool socks"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
body = res.json()
print(body["data"]["items"][0] if body["success"] else body["error"])
```

```ts tab="TypeScript SDK"
import { ApinoaClient } from "@apinoa/sdk"; // npm install @apinoa/sdk

const apinoa = new ApinoaClient(); // APINOA_API_KEY를 읽습니다
const { data } = await apinoa.walmart.search({ query: "wool socks" });
console.log(data.items[0]);
```

```python tab="Python SDK"
from apinoa import Apinoa  # pip install apinoa

client = Apinoa()  # APINOA_API_KEY를 읽습니다
res = client.walmart.search(query="wool socks")
print(res.data.items[0])
```

[SDK](/docs/sdks)는 모든 오퍼레이션을 감싸고, [MCP 서버](/docs/sdks#mcp-서버)는 Claude Code, Codex, Cursor에 API 전체를
줍니다.

### 5. 응답 읽기

모든 응답에는 `success`가 있고, 그다음에 `data`(또는 `error`)가 옵니다. 검색은
[`SearchResult`](/docs/api-reference/marketplaces/response-schema#searchresult)를 돌려줍니다. 줄이면 다음과 같습니다.

```json
{
  "success": true,
  "data": {
    "marketplace": "walmart",
    "query": "wool socks",
    "page": { "index": 1, "size": 47, "total": 4871 },
    "items": [
      {
        "marketplace": "walmart",
        "id": "344144554",
        "title": "Genuine Dickies Men's Wool Thermal Crew Sock, 3 Pack, Shoe Size 6-12",
        "price": { "currency": "USD", "amount": 15.98 },
        "rating": { "average": 4.7, "count": 551 },
        "inStock": true
      }
    ]
  }
}
```

### 6. 플랫폼 바꾸기

플랫폼은 경로의 한 구간입니다. 키, 파라미터 이름, 응답 형태는 그대로입니다.

```bash
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
curl "https://gateway.apinoa.com/v1/shopify/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
```

## 공통 규칙

이 문서의 모든 엔드포인트에 해당합니다.

### 기본 URL

```
https://gateway.apinoa.com/v1/{platform}/{operation}
```

`{platform}`은 마켓플레이스(`amazon`, `walmart`, `shopify`, `tiktokshop`, `aliexpress`), 소셜 플랫폼(`tiktok`,
`instagram`, `youtube`, `reddit`, `x`, `threads`, `linkedin`), 검색엔진(`google`, `bing`, `naver`와
[그 밖의 엔진](/docs/api-reference/serp)), AI 답변 엔진(`chatgpt`, `gemini`, `google-aio`, `google-ai-mode`,
`naver-ai-brief`, `naver-ai-tab`) 중 하나입니다. `{operation}`은 소문자이며 단어는 하이픈으로 잇습니다
(`image-search`). [`GET /v1/marketplaces`](https://gateway.apinoa.com/v1/marketplaces)가 모든 플랫폼과
오퍼레이션을 나열합니다.

### GET 또는 POST

모든 오퍼레이션은 파라미터를 `GET`의 쿼리 문자열로도, `POST`의 JSON 본문으로도 받습니다.
둘은 같습니다. 예외는 이미지 검색과 AI 답변입니다. 이미지는 URL에 들어가지 않으므로 이미지 검색은 `POST`만 받고,
AI 답변은 입력을 JSON 본문으로 받습니다.

```bash
curl -X POST "https://gateway.apinoa.com/v1/walmart/search" \
  -H "x-api-key: $APINOA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query": "wool socks", "priceMax": 30}'
```

알 수 없는 파라미터는 조용히 무시되지 않고, 그 이름을 밝힌 `400`이 됩니다.

### 응답 봉투

모든 응답은 `success`와, 그다음 `data` 또는 `error`가 담긴 JSON입니다.

```json
{
  "success": false,
  "error": { "code": "INVALID_PARAMS", "message": "(root): Unrecognized key(s) in object: 'nope'" },
  "requestId": "8d76f93c85cc4e9f911e2d0de23334c4"
}
```

`error.code`는 바뀌지 않으며 [Errors](/docs/errors)에 정리되어 있습니다. `error.message`는 사람이 읽는 용도입니다. 고객 지원에 문의할 때는
`requestId`(`x-request-id` 헤더로도 보냅니다)를 알려 주세요.

### 응답 헤더

| 헤더 | 의미 |
|---|---|
| `x-request-id` | 요청 id. 에러 본문의 `requestId`와 같습니다 |
| `x-apinoa-cost` | 이 호출에 과금된 단위 수 |
| `x-api-version` | 응답한 API 버전(`v1`) |

### 없으면 알 수 없음

플랫폼이 밝히지 않은 필드는 기본값으로 채우지 않고 **생략합니다**. `price`가 없으면 0이 아니고,
`metrics.likes`가 없으면 좋아요 0개가 아니라 숨겨진 수입니다. 가격은 주 통화 단위의 소수 금액(`12.97`)이며
통화가 함께 옵니다. 시각은 UTC 기준 ISO 8601입니다.

### 페이지네이션

목록은 한 페이지로 응답합니다. 오퍼레이션에 따라 다음 페이지는 이렇게 요청합니다.

- **`page`** — 1부터 시작하는 페이지 번호. 번호로 페이지를 넘기는 오퍼레이션(대부분의 마켓플레이스 검색)에서 씁니다.
- **`cursor`** — 이전 페이지가 돌려준 `cursor`. 커서로 페이지를 넘기는 오퍼레이션(Shopify, 모든
  SNS 목록)에서 씁니다. 단독으로 넘기세요. 첫 호출에서 요청한 모든 것이 담겨 있습니다. 응답에 `cursor`가 없으면
  다음 페이지가 없습니다.

각 엔드포인트의 파라미터 표에 어느 쪽을 받는지 나와 있습니다.

### 가격

각 호출은 그 API의 단가로 **단위**당 과금됩니다. API별 가격은 [Pricing](/pricing)에, 호출 한 번의 가격은 각
엔드포인트 페이지에 나와 있습니다. 하루 1,000회를 넘으면 요율이 단계적으로 내려갑니다. 대부분의 호출은 1단위입니다.
더 비쌀 수 있는 경우는 각 엔드포인트의 가격 섹션에 나와 있습니다.
실패한 호출은 과금되지 않습니다.

## 다음 단계

- [Marketplace API](/docs/api-reference/marketplaces): 공통 오퍼레이션과 마켓플레이스별 지원 범위
- [SNS API](/docs/api-reference/sns): 7개 플랫폼에 걸친 공통 오퍼레이션 8개
- [SERP API](/docs/api-reference/serp): 검색엔진 16곳의 검색 결과 페이지를 하나의 스키마로
- [AI Answers API](/docs/api-reference/answers): ChatGPT, Gemini, Google, Naver의 AI가 프롬프트에 내놓는 답변
- [SDK와 MCP](/docs/sdks): TypeScript, Python, MCP 서버, OpenAPI 문서
- [Image Translate](/docs/api-reference/image-translate): 상품 이미지 속 텍스트 번역
- [Authentication](/docs/authentication): 키를 보내고 보호하는 법
- [Errors](/docs/errors): 모든 에러 코드와 대처 방법