主题
GET | POST /api/keepa/variations
获取某个变体家族的全部变体基本信息：标题、颜色、尺寸、主图、当前价、月销、评分、评论数、UPC/EAN 等。
传入家族内任意 ASIN（父 ASIN 或任一子 ASIN 均可），服务端自动解析父 ASIN 并拉取全部变体。建议优先传子 ASIN：父 ASIN 在 Keepa 偶尔没有商品记录，届时会返回"未找到该 ASIN 的产品数据"。
Keepa 官方 API 没有等价能力（官方
/product一次最多查 100 个 ASIN，且不支持按父 ASIN 展开全变体），本接口为 Keepamore 独有。
接口
GET https://mcp.keepamore.com/api/keepa/variations
POST https://mcp.keepamore.com/api/keepa/variations计费
| 场景 | units |
|---|---|
| 正常返回变体列表 | 5 units / 次 |
| 该 ASIN 无变体（单品） | 1 unit（自动退回 4 units） |
- 单品（
isStandalone: true）时只产生了一次产品查询成本，因此只收 1 unitdetailLevel等附加参数 不会 额外计费- 翻页 / 不同
detailLevel视为不同请求，各自独立计费（1 小时内命中缓存也照常计费，与 product / bestseller 语义一致；400 变体家族翻完 8 页 = 40 units，按需取页）- 5 分钟内完全相同参数的请求命中 dedup，不重复计费
参数（GET 走 Query String；POST 走 JSON body）
| 名称 | 类型 | 必填 | 默认 | 约束 | 说明 |
|---|---|---|---|---|---|
domain | integer | ✅* | — | 1–12 | 站点 ID，参见 domain 映射。也可用 domainId / country 别名 |
asin | string | ✅ | — | 10 位 | 变体家族内任意 ASIN（父或子均可） |
detailLevel | enum | full | — | summary / lite / full，语义见下 | |
page | integer | 0 | ≥ 0 | 变体列表分页页码，从 0 开始 | |
perPage | integer | 1000 | 1–4000 | 每页变体数。HTTP API 默认 1000 条；需要一次全量可显式调大 |
*
domain/domainId/country三选一，多个同时传入时必须一致。默认值说明：HTTP API 的消费方是程序，不受 AI 上下文限制，因此默认
detailLevel=full+ 每页 1000 条；需要一次拿全量时显式调大perPage（≤4000，对齐亚马逊变体系列展示上限）。MCP 工具keepa_get_variations面向 AI，默认summary+ 每页 50 条。
响应
json
{
"code": "0000",
"msg": "ok",
"data": {
"country": "us",
"domainId": 1,
"inputAsin": "B0H2HG3P8J",
"parentAsin": "B0HFRJ21Z5",
"isStandalone": false,
"variationsCount": 400,
"variations": [
{
"asin": "B0H2HG3P8J",
"title": "Miracase Silicone & Magnetic for iPhone 15 Pro Max Case, Glass Blue",
"color": "Glass Blue",
"size": "iPhone 15 Pro Max",
"swatchImage": "019WF1juxGL.jpg",
"imagesCSV": "41aH4MDfVBL.jpg",
"stats": { "price": 2099, "amazonPrice": -1, "listPrice": 2299, "buyboxPrice": 2099, "bsr": 15, "rating": 45, "reviewCount": 84208, "countNew": 1 },
"monthlySold": 50,
"parentAsin": "B0HFRJ21Z5",
"upcList": ["1983524252012"],
"lastUpdate": 8223110
}
],
"_pagination": { "page": 0, "perPage": 50, "total": 400, "totalPages": 8 },
"fromCache": false,
"responseShape": { "detailLevel": "summary" }
}
}| 字段 | 说明 |
|---|---|
parentAsin | 解析出的父 ASIN；isStandalone: true 时为 null |
isStandalone | true 表示该 ASIN 无变体（单品），variations 为空数组，仅收 1 unit |
variationsCount | 全量变体总数（非当前页条数） |
_pagination | 仅在一页装不下或 page > 0 时出现 |
fromCache | 是否命中 1 小时结果缓存 |
每个变体的字段
summary级的stats是投影后的命名字段（单位与 product 接口一致：价格为分、日本站为日元、rating为评分×10、-1=无数据）：
| 字段 | 含义 | 对应 Keepa 索引 |
|---|---|---|
price | 新品最低价 | current[1] |
amazonPrice | Amazon 自营价 | current[0] |
listPrice | List Price | current[4] |
buyboxPrice | Buy Box 价（含运费） | current[18] |
bsr | 销售排名 | current[3] |
rating | 评分×10 | current[16] |
reviewCount | 评论数 | current[17] |
countNew | 在售新品 offer 数 | current[11] |
lite/full级保留原始stats对象（current36 长度索引数组）swatchImage/imagesCSV是图片文件名，完整 URL：https://m.media-amazon.com/images/I/<文件名>upcList/eanList/gtinList仅部分变体有（亚马逊未收录时无此字段）
detailLevel
| 级别 | 体积 | 说明 |
|---|---|---|
summary | 最小 | 白名单摘要字段，stats 投影成命名字段（不含 itemHighlights） |
lite | 中 | 保留全部字段，但删除 csv；reviews.ratingCount / reviewCount 只留最新一组 |
full | 最大 默认 | 原始数据原样（含完整 csv 价格历史与 reviews 全量序列） |
变体数量可达数百个：
full+ 全量分页下一个 400 变体家族的响应约 1.6MB；只需要对比价格/月销等基本信息时建议summary+perPage控制体积。
示例
bash
# 请将 km_xxx 替换为你的 API Key
# 1) GET，精简输出：第一页 50 条（summary 投影字段，适合快速对比）
curl "https://mcp.keepamore.com/api/keepa/variations?domain=1&asin=B0H2HG3P8J&detailLevel=summary&perPage=50" \
-H "X-API-Key: km_xxx"
# 2) GET，默认行为：原始数据 + 每页 1000 条（detailLevel=full + perPage=1000）
curl "https://mcp.keepamore.com/api/keepa/variations?country=us&asin=B0HFRJ21Z5" \
-H "X-API-Key: km_xxx"
# 3) POST，JSON body
curl -X POST "https://mcp.keepamore.com/api/keepa/variations" \
-H "X-API-Key: km_xxx" \
-H "Content-Type: application/json" \
-d '{
"domain": 1,
"asin": "B0H2HG3P8J",
"detailLevel": "summary",
"page": 0,
"perPage": 100
}'js
// 请将 km_xxx 替换为你的 API Key
const URL = "https://mcp.keepamore.com/api/keepa/variations";
const HEADERS = { "X-API-Key": "km_xxx" };
// 1) GET：精简输出，第一页 50 条
const r1 = await fetch(`${URL}?domain=1&asin=B0H2HG3P8J&detailLevel=summary&perPage=50`, {
headers: HEADERS,
});
const { data } = await r1.json();
console.log(`父 ASIN ${data.parentAsin} 共 ${data.variationsCount} 个变体`);
for (const v of data.variations) {
console.log(v.asin, v.color, v.size, v.stats?.price);
}
// 2) POST：默认行为（detailLevel=full + perPage=1000）
const r2 = await fetch(URL, {
method: "POST",
headers: { ...HEADERS, "Content-Type": "application/json" },
body: JSON.stringify({ domain: 1, asin: "B0H2HG3P8J" }),
});
console.log(await r2.json());python
# 请将 km_xxx 替换为你的 API Key
import requests
URL = "https://mcp.keepamore.com/api/keepa/variations"
HEADERS = {"X-API-Key": "km_xxx"}
# 1) GET：精简输出，第一页 50 条
r1 = requests.get(URL, params={"domain": 1, "asin": "B0H2HG3P8J",
"detailLevel": "summary", "perPage": 50},
headers=HEADERS, timeout=180)
data = r1.json()["data"]
print(f'父 ASIN {data["parentAsin"]} 共 {data["variationsCount"]} 个变体')
for v in data["variations"]:
print(v["asin"], v.get("color"), v.get("size"), (v.get("stats") or {}).get("price"))
# 2) POST：默认行为（detailLevel=full + perPage=1000）
r2 = requests.post(URL, json={"domain": 1, "asin": "B0H2HG3P8J"},
headers=HEADERS, timeout=180)
print(r2.json()["data"]["variationsCount"])php
<?php
// 请将 km_xxx 替换为你的 API Key
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client();
$resp = $client->get('https://mcp.keepamore.com/api/keepa/variations', [
'headers' => ['X-API-Key' => 'km_xxx'],
'query' => ['domain' => 1, 'asin' => 'B0H2HG3P8J', 'detailLevel' => 'summary', 'perPage' => 50],
'timeout' => 180,
]);
echo $resp->getBody();java
// 请将 km_xxx 替换为你的 API Key（Java 11+ 标准库）
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
.uri(URI.create("https://mcp.keepamore.com/api/keepa/variations?domain=1&asin=B0H2HG3P8J&detailLevel=summary&perPage=50"))
.header("X-API-Key", "km_xxx")
.timeout(Duration.ofSeconds(180))
.GET()
.build();
HttpResponse<String> resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());go
// 请将 km_xxx 替换为你的 API Key（Go 标准库 net/http）
package main
import (
"fmt"
"io"
"net/http"
"time"
)
func main() {
url := "https://mcp.keepamore.com/api/keepa/variations?domain=1&asin=B0H2HG3P8J&detailLevel=summary&perPage=50"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("X-API-Key", "km_xxx")
client := &http.Client{Timeout: 180 * time.Second}
resp, err := client.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}和 MCP 的对应
- MCP 工具：
keepa_get_variations