openclaw-voc-skill/openclaw-skills/xiaohongshu/xiaohongshu-search-notes/api-config.json

{
  "name": "xiaohongshu-search-notes",
  "displayName": "小红书搜索笔记",
  "description": "按关键词在小红书搜索笔记，获取相关笔记列表（图文/视频）、作者、互动数据（点赞/评论/收藏）。适用于品类种草内容发现、竞品笔记监控、VOC素材采集、爆款选题挖掘。",
  "category": "xiaohongshu",
  "version": "1.0.0",
  "endpoint": {
    "method": "GET",
    "url": "https://server.fmode.cn/thapi/v1/xiaohongshu/app/search_notes",
    "headers": {
      "Authorization": "Bearer gqsZHfMWgAiMwV+ITbmZy0qALADWBZVS7QnV7kKJe9CwzgWgJG+7bwK+GQ==",
      "Accept": "application/json"
    }
  },
  "parameters": {
    "type": "object",
    "required": [
      "keyword",
      "page"
    ],
    "properties": {
      "keyword": {
        "type": "string",
        "description": "搜索关键词，支持品类词/品牌词/人群词，如 '乳酸菌素片'、'护肝片'、'猴菇饮'、'儿童益生菌'"
      },
      "page": {
        "type": "integer",
        "description": "页码，首页传 1，下一页递增。每页固定返回 20 条笔记",
        "default": 1,
        "minimum": 1
      },
      "sort": {
        "type": "string",
        "description": "排序方式：'general'=综合排序（默认，平衡）；'time_descending'=最新发布（时效优先）；'popularity_descending'=最热门（爆款优先）",
        "enum": [
          "general",
          "time_descending",
          "popularity_descending"
        ],
        "default": "general"
      },
      "note_type": {
        "type": "string",
        "description": "笔记类型筛选：'_0'=不限；'_1'=视频笔记；'_2'=图文笔记",
        "enum": [
          "_0",
          "_1",
          "_2"
        ],
        "default": "_0"
      }
    }
  },
  "requestTransform": {
    "query": {
      "keyword": "{{keyword}}",
      "page": "{{page}}",
      "sort": "{{sort}}",
      "note_type": "{{note_type}}"
    }
  },
  "response": {
    "type": "object",
    "description": "搜索结果（双层包装：data.data 是真正数据），含 20 条笔记列表",
    "note": "社媒数据网关响应是双层 data：顶层 data 是 HTTP 包装层，data.data 才是业务数据。items[] 每项是 {model_type, note} 包装，真正的笔记字段在 items[].note 里。",
    "keyFields": {
      "data.code": "HTTP 状态码（外层）",
      "data.data.code": "业务状态码（0=成功）",
      "data.data.msg": "业务消息（'成功' 等）",
      "data.data.success": "布尔成功标志",
      "data.data.searchId": "搜索会话 ID（翻页时保留）",
      "data.data.sessionId": "会话 ID",
      "data.data.items[]": "笔记包装列表（20 条/页），每项结构 {model_type:'note', note:{...}}",
      "data.data.items[].note.id": "笔记唯一 ID（24 位十六进制），传入 xiaohongshu-note-detail 和 xiaohongshu-note-comments 的 note_id 参数",
      "data.data.items[].note.type": "笔记类型：normal=图文、video=视频",
      "data.data.items[].note.title": "笔记标题",
      "data.data.items[].note.desc": "笔记正文摘要",
      "data.data.items[].note.timestamp": "发布时间戳（秒）",
      "data.data.items[].note.last_update_time": "最后编辑时间戳",
      "data.data.items[].note.xsec_token": "笔记访问令牌（访问详情/评论时可能需要）",
      "data.data.items[].note.user.userid": "作者 ID（24 位十六进制），传入 xiaohongshu-user-info 的 user_id 参数",
      "data.data.items[].note.user.nickname": "作者昵称",
      "data.data.items[].note.user.red_id": "作者小红书号（可读 ID）",
      "data.data.items[].note.user.red_official_verified": "是否官方认证",
      "data.data.items[].note.user.images": "作者头像 URL",
      "data.data.items[].note.liked_count": "点赞数（扁平字段，不在 interact_info 里，爆款指标）",
      "data.data.items[].note.comments_count": "评论数（字段带 s，注意复数），可用 xiaohongshu-note-comments 获取详情",
      "data.data.items[].note.collected_count": "收藏数（深度认可指标）",
      "data.data.items[].note.shared_count": "分享数（传播力指标）",
      "data.data.items[].note.nice_count": "踩/nice 数",
      "data.data.items[].note.images_list[].url": "封面图/图文笔记的图片 URL 列表",
      "data.data.items[].note.tag_info": "话题标签信息"
    }
  },
  "workflow": {
    "description": "推荐调用链",
    "steps": [
      "1. xiaohongshu-search-notes(keyword) → 获取相关笔记列表（每页 20 条）",
      "2. xiaohongshu-note-detail(note_id) → 获取单笔记完整数据（完整正文/图片）",
      "3. xiaohongshu-note-comments(note_id) → 获取该笔记评论",
      "4. xiaohongshu-user-info(user_id) → 获取作者画像（KOL/KOC 筛选）"
    ]
  },
  "usageExamples": [
    {
      "name": "品类种草内容发现",
      "input": {
        "keyword": "乳酸菌素片",
        "page": 1,
        "sort": "popularity_descending",
        "note_type": "_0"
      },
      "description": "搜索乳酸菌素片最热门的种草笔记，发现爆款内容规律和用户表达方式"
    },
    {
      "name": "最新竞品笔记监控",
      "input": {
        "keyword": "合生元益生菌",
        "page": 1,
        "sort": "time_descending"
      },
      "description": "搜索竞品品牌最新发布的笔记，监控其内容策略动向"
    },
    {
      "name": "用户痛点 VOC 素材采集",
      "input": {
        "keyword": "护肝片 踩雷",
        "page": 1,
        "sort": "general"
      },
      "description": "搜索用户发布的踩雷/避雷内容，结合 xiaohongshu-note-comments 提取真实痛点"
    },
    {
      "name": "视频内容趋势研究",
      "input": {
        "keyword": "养胃",
        "page": 1,
        "sort": "time_descending",
        "note_type": "_1"
      },
      "description": "筛选最新发布的养胃相关视频笔记，辅助新品上市内容策略规划"
    }
  ],
  "reportMapping": {
    "slides": [
      "小红书品类种草分析",
      "小红书竞品内容监控",
      "小红书用户 VOC 采集"
    ],
    "dataPoints": [
      "品类种草笔记列表",
      "笔记互动率（点赞/评论/收藏比）",
      "爆款标题/封面模式",
      "活跃 KOL/KOC 账号发现",
      "用户真实表达方式与痛点关键词（结合评论分析）"
    ]
  },
  "timeout": 60000,
  "retry": {
    "maxAttempts": 3,
    "delay": 2000,
    "backoffMultiplier": 2,
    "retryOn": [400, 429, 500, 502, 503, 504]
  },
  "notes": "本 skill 使用共享社媒数据订阅（/thapi/ 网关），不经过 APIG 计费。社媒网关偶发 400 瞬时错误，已启用 3 次重试。中文关键词会在请求时自动 URL-encode。"
}