本页目录两种接入形态快速体验智能搜索 GET /v1/cps/smart_search商品对比 POST /v1/cps/compare榜单 GET /v1/cps/rankings货架检索 GET /v1/cps/local/goods购买跳转与归因开发者分成展示红线(务必遵守)
商品推荐与购买跳转
源头淘聚合淘宝 / 京东 / 拼多多官方渠道商品,开放给 AI agent:智能搜索、推荐解释、商品对比、购买跳转一站式完成。用户跳转到官方平台下单,享受平台原售价与售后;开发者按实际成交金额获得分成。
两种接入形态
| 形态 | 流程 | 适合 |
|---|---|---|
| 货架直购 | search_goods → create_order,用户在源头淘完成支付与履约 |
标品、需要掌控下单流程的场景(见 快速开始) |
| 推荐跳转(本页) | 智能搜索 → agent 推荐 → 用户点击 buy_url 跳转官方平台购买 |
全品类推荐、"帮我挑一个"类对话 |
两种形态可以混用:推荐流里也可以对货架商品直接下单。
快速体验
curl -H "X-API-Key: $YUANTOUTAO_API_KEY" \
"https://api.yuantoutao.com/v1/cps/smart_search?q=保温杯&mode=price&page_size=3"
返回的商品对象里,buy_url 是带归因的购买跳转链接,page_url 是可展示给用户的商品详情页。
智能搜索 GET /v1/cps/smart_search
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| q | string | 是* | 搜索词,支持自然语言(如"打游戏用的手机 2000 左右") |
| mode | string | 否 | balanced(默认)/ quality / price——三种排序权重预设,见下文 |
| platforms | string | 否 | tbk,jd,pdd 逗号分隔,限定平台(不填=全部) |
| category | string | 否 | 类目筛选 |
| budget_min / budget_max | number | 否 | 预算区间(元) |
| page / page_size | number | 否 | 默认 1 / 20(上限 50) |
| live | 0/1 | 否 | 1 = 同时并行查询各平台实时在售数据(多花约 1 秒,覆盖更广,建议对话场景开启) |
* q、category、platforms 至少提供一个。
排序模型(可解释三因子):每个商品返回 score 与 breakdown:
breakdown.rel相关性——搜索词与商品标题/品牌/类目的匹配度breakdown.quality质量——店铺层级(官方旗舰店/旗舰店/专卖店高于普通店铺)× 销量 × 服务保障breakdown.value价值——同类比价中的价格位置 × 优惠力度breakdown.reasons[]—— 现成可引用的推荐理由(如"官方旗舰/自营渠道""月销 3万+""比原价低 62%")
mode 决定三者权重:balanced(0.45/0.30/0.25,默认)、quality(0.35/0.45/0.20,用户在意正品/耐用)、price(0.40/0.15/0.45,用户在意便宜/划算)。根据用户措辞静默选择即可,无需追问用户。
响应示例
{
"schema": "v1", "q": "手机", "mode_used": "balanced",
"coverage": {"local": 34, "tbk": 20, "pdd": 2, "jd": 0}, "total": 48,
"items": [{
"platform": "tbk", "item_id": "xxx", "title": "…",
"shop_name": "…官方旗舰店", "shop_type": "天猫", "shop_tier": 0.95,
"price_final": 298800, "price_original": 359900, "coupon_amount": 5000,
"sales_tip": "月销 30000", "image": "https://…",
"score": 0.753,
"breakdown": {"rel": 1.0, "quality": 0.94, "value": 0.29, "shop_tier": 0.95,
"reasons": ["官方旗舰/自营渠道", "月销 3万+", "比原价低 17%"]},
"page_url": "https://yuantoutao.com/tao/xxx.html",
"buy_url": "https://yuantoutao.com/go/tbk/xxx",
"content": "…种草文案…"
}]
}
金额单位人民币分(与全平台一致)。
推荐话术规范(重要)
breakdown.reasons里的理由可以直接引用给用户;除此之外不要补充"用户评价说…"之类的内容(平台不提供评价正文,引用聚合信号:好评率/销量/店铺层级)。- 价格转述时注明"价格以官方平台下单页为准"。
商品对比 POST /v1/cps/compare
POST /v1/cps/compare
{"items": "tbk:431xxx,pdd:9648xxxxx"}
返回 2-6 个商品的对比矩阵:券后价、相对类目均价(vs_category_avg)、店铺层级、销量、品牌与规格行(spec)。适合在推荐前生成对比表。
榜单 GET /v1/cps/rankings
| 参数 | 说明 |
|---|---|
| platform | tbk / jd / pdd,不填=全部 |
| sort | sales / latest / coupon / discount(默认 latest) |
| category / page / page_size | 同上 |
榜单服务端缓存 1 小时,适合"现在什么卖得好"类问题与首屏商品流。
货架检索 GET /v1/cps/local/goods
已精选入库商品的轻量检索(默认相关性排序,sort=sales|price|latest 可选)。响应含 score/breakdown。单品详情:GET /v1/cps/local/goods/:platform/:itemId。
购买跳转与归因
- 商品对象的
buy_url即带归因的购买链接(HTTP 302 到官方平台)。用户从点击到下单的佣金归因由平台完成,agent 无需任何额外参数。 - 如需区分"哪个终端用户/会话"产生的转化,在
buy_url后追加?ak=<你的归因参数>(选填)。 - 用户点击后进入淘宝/京东/拼多多官方页面,价格与优惠以平台下单页为准;售后由对应平台商家按平台规则提供。
开发者分成
- 经开放接口或 AI 助手促成的有效商品订单,开发者获得实际成交金额 3% 的分成(多数好价商品参与;话费充值等虚拟商品及部分特殊商品以结算账单为准)。
- 每月 27 日至月末结算上月分成,满 10 元可提现。完整规则见 rewards.html。
- 分成与货架直购订单的分成体系一致,统一在开发者控制台查看。
展示红线(务必遵守)
- 不出现"返利""拿佣金""联盟"等字样——对用户的口径是"帮你找到的好价"。
- 不编造用户评价(平台不提供评价正文,只用聚合信号:销量/好评率/店铺层级)。
- 不承诺价格,注明"以平台为准"。
- 推荐理由使用接口返回的
breakdown.reasons,不要自行编造卖点。