---
title: "快速入门"
description: "几分钟内创建 API 密钥并完成第一次平台搜索。"
---

## 概览

Apinoa 是一个面向电商平台商品数据的 API。亚马逊、eBay、Shopify、沃尔玛和速卖通通过同一个密钥、以同一套规范化结构
返回数据：平台只是路径中的一段，请求的其余部分完全相同。同一个密钥也可以使用图片翻译。

## 快速开始

### 1. 创建账号

在 [apinoa.com](https://apinoa.com) 注册并验证邮箱地址。

### 2. 充值额度

没有套餐需要选择，注册也无需绑定银行卡。按调用从预付余额中扣费，单价见[价格页](/pricing)。
在 **控制台 > 余额** 查看剩余额度并充值。如想先行评估，可在控制台的免费额度卡片中申请 **$1 免费额度**。

### 3. 生成 API 密钥

前往 **控制台 > API 密钥** 创建新密钥。可以选择设置前缀，方便识别。

```bash
# API 密钥的格式如下：
myapp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

请妥善保管 API 密钥，它只在创建时显示一次。一个密钥即可调用所有平台。

### 4. 发送第一个请求

在 `x-api-key` 请求头中携带密钥：

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

同样的请求也可以用 JSON 请求体代替查询字符串传参，两种方式完全等价：

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

```javascript
const url = new URL("https://gateway.apinoa.com/v1/walmart/search");
url.searchParams.set("query", "wool socks");

const res = await fetch(url, { headers: { "x-api-key": "YOUR_API_KEY" } });
const { success, data, error } = await res.json();
console.log(success ? data.items[0] : error);
```

### 5. 理解响应

所有响应都使用同一个信封：`success`，然后是 `data` 或 `error` 之一。搜索会在 `data` 中返回
[`SearchResult`](/docs/api-reference/marketplaces/response-schema)：

```json
{
  "success": true,
  "data": {
    "marketplace": "walmart",
    "query": "wool socks",
    "page": { "index": 1, "size": 40, "total": 1000 },
    "items": [
      {
        "marketplace": "walmart",
        "id": "996425081",
        "title": "Merino Wool Hiking Socks, 3 Pack",
        "price": { "currency": "USD", "amount": 18.97 },
        "rating": { "average": 4.6, "count": 1204 },
        "inStock": true
      }
    ]
  }
}
```

`price.amount` 使用带小数的主单位。字段缺失表示平台没有提供该信息，绝不会用默认值填充，所以没有 `price` 不代表价格为 0。

出错时，信封里会带上错误码和错误信息：

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "brands: Unrecognized key(s) in object: 'brands'"
  }
}
```

### 6. 换一个平台试试

只需修改路径中的平台。密钥、参数和响应结构都保持不变：

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

`GET /v1/marketplaces` 会列出所有平台、支持的操作、每个操作的费用，以及每个操作输入参数的 JSON Schema。

## 可用 API

| API | 接口 | 说明 |
|-----|-----------|-------------|
| 平台 | `search`、`browse`、`categories`、`image-search`、`product`、`reviews` | 用一套结构获取亚马逊、eBay、Shopify、沃尔玛和速卖通的商品数据 |
| 图片翻译 | 翻译、OCR、支持的字体 | 在保留原始视觉风格的同时替换商品图片中的文字 |
| 速卖通 | `search`、`product`、`categories`、`browse`、`image-search` | 速卖通商品数据 |

## 下一步

- [平台](/docs/api-reference/marketplaces) -- 各平台之间相同与不同的地方
- [响应结构](/docs/api-reference/marketplaces/response-schema) -- 你可能收到的全部字段
- [筛选](/docs/api-reference/marketplaces/filters) -- 所有平台通用的价格、品牌、评分、成色和排序
- [认证](/docs/authentication) -- API 密钥认证
- [版本管理](/docs/versioning) -- `/v1`、已弃用的无版本 URL 及其停用日期
- [错误码](/docs/errors) -- 完整错误参考