快速入门

创建 API 密钥，发出第一个调用，并了解所有接口共用的约定。

快速开始

2. 充值余额

调用按价格页面上的费率从预付余额中扣费；无需选择套餐。控制台 > 余额显示剩余金额并可在此充值。如需先行评估，可在控制台的免费额度卡片中申请免费额度：每个账户合计最多 $1，第 3 步的 $0.10 也计入其中。

3. 创建 API 密钥

最快的方式是直接在终端中获取密钥。在项目目录下运行：

npx apinoa-mcp login

在打开的页面中登录 apinoa（没有账户可以新建），输入终端显示的代码并批准，密钥就会以 APINOA_API_KEY 写入 .env。通过这种方式或登录托管版 MCP 服务器首次获得的密钥附带 $0.10 评估额度，每个账户仅限一次。详见身份验证。

也可以前往控制台 > API 密钥创建密钥。密钥仅在创建时显示一次，请立即保存：

export APINOA_API_KEY="myapp_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

一个密钥适用于所有 API。本文档中的示例都从环境变量 APINOA_API_KEY 读取密钥：可以像上面那样 export，也可以加载 npx apinoa-mcp login 写入的 .env。

4. 发出第一个调用

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

SDK 封装了每个操作，MCP 服务器则把整个 API 交给 Claude Code、Codex 和 Cursor。

5. 读取响应

每个响应都包含 success，然后是 data（或 error）。搜索返回 SearchResult；节选如下：

{
  "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. 切换平台

平台是路径中的一段。密钥、参数名和响应结构都保持不变：

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 及其他引擎）或 AI 回答引擎（chatgpt、gemini、google-aio、google-ai-mode、 naver-ai-brief、naver-ai-tab）。{operation} 为小写，单词之间用连字符连接（image-search）。 GET /v1/marketplaces 列出所有平台和操作。

GET 或 POST

每个操作都可以用 GET 的查询字符串发送参数，也可以用 POST 的 JSON 请求体发送，两者等价。例外是图片搜索和 AI 回答：图片无法放入 URL，所以图片搜索仅支持 POST；AI 回答以 JSON 请求体接收输入。

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 之一：

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

error.code 是稳定的，记录在 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 列出每个 API 的价格，每个接口的页面说明一次调用的费用。每日调用超过 1,000 次后费率逐级下降。大多数调用花费一个单位；每个接口的价格部分会说明何时可能花费更多。失败的调用不计费。

后续步骤

Marketplace API：共享的操作以及各电商平台支持哪些
SNS API：七个平台上的八个共享操作
SERP API：16 个搜索引擎的搜索结果页，同一套结构
AI Answers API：ChatGPT、Gemini、Google 和 Naver 的 AI 对提示的回答
SDK 与 MCP：TypeScript、Python、MCP 服务器和 OpenAPI 文档
Image Translate：翻译商品图片中的文字
Authentication：发送并保护你的密钥
Errors：每个错误代码以及应对方法