小红书聚光投放API Skill

功能特性

多账号管理：支持多个聚光广告主账号，每个账号可独立配置 app_id / app_secret / token / advertiser_id
SDK核心：覆盖账户、计划、单元、创意、笔记、报表、工具类接口
OAuth授权：支持授权码换Token、自动刷新Token
数据报表：日报、周报、月报、对比分析，一键生成
自动优化规则引擎：监控消耗、CTR、CPL、CPM等关键指标
增强模块：缓存、重试、CSV导出、异常检测
安全设计：SkillHub包只包含 sample 配置，不包含任何真实 token、secret、advertiser_id

快速开始

单账号模式

cp config.json.sample config.json
cp token.json.sample token.json
# 填入你的 app_id、app_secret、token_file、advertiser_id 等信息

from sdk import XiaohongshuJuguangSDK
sdk = XiaohongshuJuguangSDK(config_path="config.json")
print(sdk.get_realtime_report("account"))

多账号模式

cp accounts.json.sample accounts.json
mkdir -p tokens
# 在 accounts.json 中配置多个账号，每个账号可独立配置 app_id/app_secret/token_file/advertiser_id

from sdk import XiaohongshuJuguangSDK

# 默认账号
sdk = XiaohongshuJuguangSDK(multi_config_path="accounts.json")

# 指定账号
sdk_a = XiaohongshuJuguangSDK(multi_config_path="accounts.json", account_key="account_a")
sdk_b = XiaohongshuJuguangSDK(multi_config_path="accounts.json", account_key="account_b")

账号管理命令

python3 account_manager.py list
python3 account_manager.py set-default account_a
python3 account_manager.py add account_c "Account C" YOUR_ADVERTISER_ID ./tokens/account_c.json YOUR_APP_ID YOUR_APP_SECRET
python3 account_manager.py exchange-token account_a
python3 account_manager.py report-today all

多账号配置示例

{
  "version": "multi_account_v1",
  "default_account": "account_a",
  "api_base_url": "https://adapi.xiaohongshu.com/api/open/jg",
  "accounts": [
    {
      "key": "account_a",
      "name": "Account A",
      "advertiser_id": "YOUR_ADVERTISER_ID_A",
      "app_id": "YOUR_APP_ID_A",
      "app_secret": "YOUR_APP_SECRET_A",
      "token_file": "./tokens/account_a.json",
      "enabled": true
    }
  ]
}

接口覆盖

| 模块 | 说明 | |------|------| | OAuth | 授权码换Token、刷新Token | | 账户 | 预算、订单、余额查询 | | 计划 | 列表、编辑、状态修改、新创编 | | 单元 | 列表、编辑、状态修改、出价、关键词 | | 创意 | 搜索、编辑、状态修改 | | 笔记 | 笔记列表 | | 报表 | 账户/计划/单元/创意/关键词/笔记/简单投/批量 | | 工具 | 词包、行业、人群、定向、关键词、历史、校验 |

关键规则

消耗统计优先账户层：账户层报表是最稳定的数据源，下层报表可能因权限返回空数据。
预算单位注意：预算/出价接口常用“分”，资金/余额接口可能是“元”，调用前必须确认。
多账号防串号：每个账号使用独立 token_file；如果每个聚光账号对应不同应用，应在账号级配置 app_id/app_secret。
写操作谨慎：涉及出价、预算、创建/暂停计划等操作，应先由用户确认。

安全说明

发布到 SkillHub 的包内不得包含真实：

app_secret
access_token / refresh_token
advertiser_id
客户名称或业务数据

本包仅提供 sample 文件，真实配置请在本地复制 sample 后自行填写。