小红书商品研究 API:搜索卡片与已知 SKU 布局
读取小红书关键词首屏或已知 SKU,验证业务状态和嵌套卡片,区分会话、商品标识与原始价格,不自动翻页或串联评论。

小红书商品响应更像页面布局,不是一个平铺的商品对象。搜索卡片外面有id,content里面也有id;详情有些容器不带直接content,却装着下一层cards。把它们直接拍平成字典,可能把有效嵌套内容当成缺失,也可能拿布局位置的标识去查商品。
这篇小红书商品研究API教程只准备一次关键词首屏,或者一次独立选择的已知SKU查询。2026年11月8日修订依据公开参考、8月保存样本和离线测试,没有新业务调用,没有证明搜索到详情的串联,也没有拉取评论。9月27日的旧设计与代码仍保留,可按历史版本核对。
先说结论
- 搜索示例使用keyword、page1、空search_id与source explore_feed,没有声明limit输入。
- 已知SKU使用sku_id,source和pre_page选mall_search;pre_page是上下文,不是页码。
- completed之后仍要验证outputs[0].data内的整数code0和布尔success true,再读取布局。
- 嵌套卡片、原始价格与规格ID要保留;一个页面不等于完整商品目录、库存数量或商业推荐。
保留的封面是搜索、商品、评论串联概念图。背包价格、评价文字、五星与计数均是画面示意,不是保存样本或本次修订的结果。
选择一个明确的商品任务
| 任务 | 当前参考 | 首请求内容 |
|---|---|---|
| 看关键词返回的商品卡片 | 商品搜索 | keyword、page1、空search_id、explore_feed |
| 看一个已知SKU的布局 | 商品详情 | sku_id、source与pre_page均为mall_search |
搜索只必填keyword,其余三个字段按本例显式选择默认值。详情只必填sku_id,上下文字符串并非必填。代码中的24位十六进制检查是针对现有参考的本地约束,schema没有相应长度或正则限制;被本地拒绝不等于上游真的收到并拒绝了请求。
不要拿商品链接、布局卡片id或另一个规格ID代替用户选择的SKU。README描述可以把商品标识交给详情接口,但这里两个保存样本不能证明这个链路:详情早于搜索,查询的SKU也不在搜索六个卡片里。两次选择要分别保留来源。
历史search-products参数页,包含keyword、page、search_id和source,生成data为空。旧说明写20条,但完整保存样本只有六张商品卡片,本次不承诺固定返回条数。
让已有项目和agent从一次读取开始
已有项目复用本地SANDBASE_API_KEY与requests依赖,不需要替换原有密钥管理,也不要把密钥写进提示词。已连接的agent需要的是具体任务与停止条件。“帮我调研这个类目”范围过宽,容易变成遍历商品、查详情和评论的多次调用。
新项目可使用setup skill和Markdown quickstart。可以这样交代:“实现OpenAI关键词的一次首屏搜索,page1、search_id为空,验证业务状态,区分卡片外层id和content.id,完成后停止。离线测试异常布局,不翻页、不打开App链接、不自动查每个SKU。”已知SKU场景则改为明确的详情任务。
11月8日inspect显示两端点各$0.01,具备组织共享每日100次合资格调用额度,UTC零点重置。不是每个接口各100次,也没有读取你的剩余额度。一次列价$0.01,两次明确选择的请求列价合计$0.02,尚未考虑适用额度。本次未测试业务失败的计费行为,不能把README里的计费说法升级成实测保证。
Python:验证状态,保留原始布局
通过python -m pip install requests安装依赖,并在本地配置密钥。下面使用Model API的POST路由,body只含操作参数;目录GET地址是导航路径,不能替换这里的请求方法。函数一次最多发送一个请求。
import os
import re
import json
import requests
API = "https://api.sandbase.ai/v1/api/xiaohongshu/app-v2"
def optional_json(raw):
if not isinstance(raw, str):
return None
try:
return json.loads(raw)
except (ValueError, TypeError):
return None # Keep the original field; truncated inner JSON is not a failed response.
def first_request(task, value):
if not isinstance(value, str) or not value.strip() or value != value.strip():
raise ValueError("Provide an unchanged nonblank keyword or SKU string")
if task == "search":
route = "search-products"
params = {"keyword": value, "page": 1, "search_id": "", "source": "explore_feed"}
elif task == "detail":
# Local guard for these references; the provider schema has no hex pattern.
if not re.fullmatch(r"[0-9a-fA-F]{24}", value):
raise ValueError("Choose a 24-character hexadecimal SKU string")
route = "product-detail"
params = {"sku_id": value, "source": "mall_search", "pre_page": "mall_search"}
else:
raise ValueError("Choose search or detail")
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(
f"{API}/{route}",
headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
json=params, timeout=(10, 90), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"SandBase HTTP {response.status_code}; stopped")
body = response.json()
except requests.RequestException:
raise RuntimeError("Network failure; no automatic retry") from None
except ValueError:
raise RuntimeError("Invalid response JSON") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0]")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Missing documented outputs[0].data object")
if type(payload.get("code")) is not int or payload["code"] != 0 or payload.get("success") is not True:
raise RuntimeError("Provider result is not integer code zero and boolean success")
data = payload.get("data")
if not isinstance(data, dict) or not isinstance(data.get("module"), dict):
raise RuntimeError("Missing layout module")
cards = data["module"].get("data")
if not isinstance(cards, list) or any(not isinstance(card, dict) for card in cards):
raise RuntimeError("Missing or malformed module data array")
if task == "search":
for card in cards:
if card.get("card_name") != "cosmos_search_goods_card":
continue
content = card.get("content")
if not isinstance(content, dict) or not isinstance(content.get("id"), str) or not content["id"]:
raise RuntimeError("Goods card has no content ID; wrapper ID is not a SKU")
else:
node = data
for field in ["biz_info", "common", "common"]:
node = node.get(field) if isinstance(node, dict) else None
if isinstance(node, dict) and "sku_id" in node and node["sku_id"] != value:
raise RuntimeError("Present echoed SKU differs from the selected SKU")
return payload
if __name__ == "__main__":
result = first_request("search", "OpenAI")
print("Returned layout cards:", len(result["data"]["module"]["data"]))如果要详情,只替换main中的调用为result = first_request("detail", "YOUR_SELECTED_SKU"),占位值换成实际24位十六进制字符串。下面打印布局卡片数的一行对两种返回都适用,可以保留。不要在搜索后再追加详情;卡片数量也不等于商品数或规格数。
helper原样返回业务对象。搜索里不认识的非商品卡片会保留,只有明确标记为商品的卡片才检查content标识。详情不要求每张卡片都有直接content。若返回明确回显SKU,就和用户选择的字符串比较;精简README没有回显时,不填造ID,也不声称独立核验了身份。
optional_json只用于已知的JSON编码字符串,不递归解码全部字段。字符串被截断时返回None,原值不受影响;没有eval、远端引用解析、App跳转或媒体下载。这些检查针对已观察布局,不是对未来所有业务结构的承诺。
搜索样本:六张卡片与一个会话
保存记录c2fb3714-b06c-498b-bd41-b14ec63cdeb1的时间为8月20日09:43:16.144 UTC,输入OpenAI、page1、空search_id和explore_feed。完整业务对象是整数code0、布尔success true,data.module.data里有六个cosmos_search_goods_card。下面投影保留根层分页信息和首卡标识:
{
"page": 1,
"next_page": 2,
"search_id": "4e54af57e5a846c2",
"first_card": {
"card_name": "cosmos_search_goods_card",
"id": "cosmos_search_goods_card_1",
"content_id": "68922dd24daa7100015f016f"
}
}外层id只是布局位置,content.id才是商品标识。根层search_id属于搜索会话,不是SKU或API密钥。以后若单独实现续页,需要在相同关键词与上下文中携带返回的search_id及next_page。旧文“不是把返回值再传回”的说法不正确;本次并未执行第二页,也不宣称覆盖全部商品。
首张完整卡片的price是35.7、origin_price是42,foreign_price展示约£3.94。数值单位与币种尚未独立确认,不能自动作精确换算。stock_status1是标记,不是库存件数;样本里名为vendor_id的字段实际装着头像URL,也说明不能只凭字段名判断它可作关联ID,代码不会访问该链接。
另一份无日期README仅保留一张卡片,content ID和会话值不同,还省略部分标题与价格字段。六张对一张不能解释成下降、续页结果或字段消失;不要给README套用8月样本时间。
详情的嵌套容器与SKU规格
详情保存记录cd24f485-540f-4a68-867e-e68e400969a2的时间为8月20日09:40:42.848 UTC,选择SKU669ddd44e05f3700011067ed,两个上下文均为mall_search。它早于搜索,且是另一个商品。六个module卡片名分别为header_carousel、primary、gd_comments、gd_multi_notes_card、gd_shop、gd_info_card。
以下投影记录卡片名与是否存在content键,没有把缺失的content改成空对象:
[
{
"card_name": "header_carousel",
"has_direct_content": true,
"nested_card_count": 0
},
{
"card_name": "primary",
"has_direct_content": false,
"nested_card_count": 2
},
{
"card_name": "gd_comments",
"has_direct_content": true,
"nested_card_count": 1
},
{
"card_name": "gd_multi_notes_card",
"has_direct_content": true,
"nested_card_count": 0
},
{
"card_name": "gd_shop",
"has_direct_content": false,
"nested_card_count": 2
},
{
"card_name": "gd_info_card",
"has_direct_content": false,
"nested_card_count": 6
}
]primary、gd_shop、gd_info_card里有下一层cards。缺少直接content不能证明没有商品、店铺或描述。carousel的content.style.sku_list包含三个不同SKU规格,README只保留第一个。返回里的new_item_id或类似SPU标识有自己的角色,不能默默替换请求SKU;存在相关规格也不意味着用户已经改选了商品。
历史product-detail参数页,sku_id必填,source与pre_page为可选上下文字符串。生成data为空,这不是嵌套布局的响应截图,也不能证明当前库存。
完整样本的deal_price和origin_price均为599,JSON编码extra_info里price_currency_origin是USD;README文字却写GBP,而且它截短的extra_info已经不是合法内层JSON。两份来源和原始字符串都应保留,不能直接解释成599美元或5.99美元。可选内层文字解析失败,也不应使整个有效外层响应变成业务失败。
delivery等标记是历史、地区相关的上下文,不是配送保证。addCart按钮、店铺服务链接、App deeplink只是数据,本教程不会执行这些动作。嵌入笔记与评论卡片也不是完整评价集合;未解析的美元符号引用继续保留未知,不补造内容或下载媒体。
错误测试的结论范围
两个接口都没有完整保存的负面样本。新错误场景来自离线mock:损坏信封、冒充整数零的布尔值、缺失或false的success、错误module类型,以及存在但不匹配的SKU回显。它们证明客户端如何停止,不能证明所有上游错误都是什么原因。非零code本身不能断定商品删除、SKU无效或登录失败。
合法业务状态下的显式空module数组仍然是空布局。价格、卖家、币种和库存缺失都记未知,不补零;缺少业务对象不能回退成成功。解析不会藏着重试或后续调用,扩展项目时需要明确哪些字段对自己的任务是必要的。
原设计与示意JSON保留
完整中文历史稿与代码保留原四段Python和下面的示意JSON。旧extract_sku_ids及sku_id是未定义占位内容,不是开箱可跑的端到端示例;统一外层信封也不能证明搜索、详情、评论和推荐共用业务结构。
{
"id": "…",
"status": "completed",
"model": "xiaohongshu/app-v2/product-reviews",
"outputs": [
{
"data": {
"code": 0,
"success": true,
"data": { "…": "…" }
}
}
]
}省略号id是示意,不是运行凭证。原文没有文字运行UUID或三步链路的完整实测证据。评价概览、情感排名、多关键词展开、推荐游标和定时监测仍属于历史设计延伸,本次没有重新核验或执行。恢复这些功能要看各自端点,不能只复用一个code零判断。
历史product-reviews参数页,包含sku_id及自身分页、筛选字段,生成data为空。该独立接口保留作背景,没有被当作当前搜索或详情示例的已测试步骤。
常见问题
搜索应该保存哪个ID? 明确商品卡片的content.id,并保留原卡片和会话上下文;外层id不是SKU。详情仍需要用户明确选择。
pre_page是上一页页码吗? 不是,它在详情里是字符串上下文,默认mall_search,与搜索的整数page不同。
价格可以直接比较吗? 先确认相容的币种、单位和观察条件。原值599、一份USD内层字符串与另一份GBP说明,不足以确定换算。
没有直接content就是没数据吗? 这些保存容器内部还有cards,先保留嵌套结构,再决定应用真正需要什么字段。
觉得有用?分享给更多人