---
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（没有账户可以新建），输入终端显示的代码并批准，密钥就会以 `APINOA_API_KEY` 写入 `.env`。
通过这种方式或登录[托管版 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-服务器)则把整个 API 交给 Claude Code、Codex 和
Cursor。

### 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` 并指出其名称，绝不会被静默忽略。

### 响应信封

每个响应都是 JSON，包含 `success`，然后是 `data` 或 `error` 之一：

```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` 不代表零，缺失的 `metrics.likes`
代表计数被隐藏，而不是零个赞。价格是以主货币单位表示的小数金额（`12.97`），并附带币种。时间采用 ISO 8601
格式，UTC 时区。

### 分页

列表以页的形式返回。根据操作不同，用以下方式请求下一页：

- **`page`** — 从 1 开始的页码，用于按页码分页的操作（大多数电商平台搜索）。
- **`cursor`** — 上一页返回的 `cursor`，用于按游标分页的操作（Shopify 以及所有 SNS 列表）。单独传入即可；
  它携带了首次调用的全部请求内容。响应中没有 `cursor` 表示没有下一页。

每个接口的参数表会说明它使用哪一种。

### 价格

每次调用按其 API 的单价以**单位**计费：[Pricing](/pricing) 列出每个 API 的价格，每个接口的页面说明一次调用的费用。
每日调用超过 1,000 次后费率逐级下降。大多数调用花费一个单位；每个接口的价格部分会说明何时可能花费更多。失败的调用不计费。

## 后续步骤

- [Marketplace API](/docs/api-reference/marketplaces)：共享的操作以及各电商平台支持哪些
- [SNS API](/docs/api-reference/sns)：七个平台上的八个共享操作
- [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)：每个错误代码以及应对方法