cmm-api

---
name: cmm-api
description: 蝉妈妈电商数据查询与视频工具：查达人（找达人/找主播/找KOL/网红筛选/粉丝画像/带货数据/带货榜单/XX带了什么货）、查商品（热销榜/爆款商品/这个商品卖得怎么样/带货达人/用户评论/商品分析）、查小店（店铺数据/小店销售/关联商品/动销分析）、查品牌（XX品牌市场表现/市场份额/竞品对比/品牌销售趋势）、查直播（直播间数据/场观人数/弹幕分析/直播商品/直播销售额）、查视频（爆款视频/热门视频/千川素材/视频带货数据/视频榜单/提取视频文案/拆解视频分镜/理解视频画面）、查品类（品类趋势/市场分析/类目数据/属性特征分析）。当用户询问抖音数据、抖音电商相关数据，或需要提取视频口播文案、拆解视频分镜、理解视频画面内容时使用此Skill。
---

# CMM API

使用此 skill 通过蝉妈妈 API Key 网关调用 CMM 数据 API 和视频工具。

## 接口地址

调用 `POST {CMM_API_BASE_URL}/v1/cmm/api/execute`。
默认 base URL：`https://ai-api.chanmama.com`。

鉴权要求：
- 优先使用 `Authorization: Bearer $CMM_API_KEY`。
- 如果调用方显式提供鉴权信息，则在 JSON body 中通过 `auth_info` 传入。

常用请求体：

```json
{
  "api": "product_basic_info",
  "query": {
    "promotion_id": "8993722"
  }
}
```

## 使用流程

### 首次使用或需要检查权限时

1. 调用权限检查接口：
   ```bash
   GET {CMM_API_BASE_URL}/v1/cmm/api/permission/list?intent=<任务描述>
   Authorization: Bearer $CMM_API_KEY
   ```
   - `intent` 为必填 Query 参数，用于简要描述任务目标和内容。
   - 若CMM_API_KEY未配置，引导用户前往蝉妈妈AI-个人中心获得KEY，并添加到环境变量。地址`https://ai.chanmama.com/setting`
   - 若会员版本为普通会员，引导前往蝉妈妈购买会员获得数据权限。地址`https://www.chanmama.com/vip/`

2. 向用户清晰展示权限信息：
   - **会员版本**：根据 `group_id` 判断会员等级
   - **可用API模块**：从 `rights` 字段提取可访问的模块列表（商品、达人、小店、品牌、直播、视频、品类）
   - **数据查询周期**：根据权限显示可查询的时间范围
   
3. 版本检查（静默）：
   - 对比返回的 `version` 与本地版本 `2026-08-27`
   - 如果有新版本，**先完成用户任务**
   - 在任务结束时提醒用户：
     > 💡 发现新版本 数据查询Skill（{version}），是否现在更新？我可以帮您自动完成。
   - 如果用户同意，重新执行安装命令刷新 skill：
     ```bash
     npx -y skills add https://cdn-cmm-ai-open.chanmama.com --skill cmm-api -y
     ```

### 正常调用流程
1. 用户需要提取单条视频的口播文案、拆解分镜或理解视频画面时，直接阅读 `references/video-tools.md`；不要把这类视频内容处理需求当成 `references/video.md` 中的数据查询。
2. 如果只有实体名称（达人名/商品名/品牌名/店铺名等）而非ID，先阅读 `references/common.md` 调用搜索API转为ID。
3. 分析数据查询需求，确定主查询实体（主语是谁？查什么？），阅读对应的references文件：
   - 涉及多实体时，按主查询实体选择
   - 示例："交个朋友直播间带货的花西子商品" → 主实体是"达人"，读 `author.md`
4. 根据意图、API 摘要和查询字段选择 API。
5. 使用参考文件中记录的字段名构造 `query`。
6. 用户需要真实调用时，使用 `scripts/call_cmm_api.py` 执行。若提供 `CMM_API_BASE_URL` 则使用该地址，否则使用默认测试地址。
7. 如果 `code != 0`，将 `msg` 中的错误信息和引导链接直接展示给用户；只有在鉴权、实体或日期等输入无法安全推断时再向用户追问。

## 日期参数处理

**日期格式**：
- 普通查询：`YYYY-MM-DD`（如 `2026-07-01`）
- 榜单查询：日榜 `YYYY-MM-DD`，周榜 `YYYYMMDD-YYYYMMDD`，月榜 `YYYYMM`

**相对日期转换**：
- 数据是T+1，"近N天"不包含今天
- "近7天" / "近30天" 的结束日期设为昨天

## 多步查询模式

以下是常见的查询模式示例，实际使用时可根据需求灵活组合API：

**模式1：名称 → ID → 详情**
```
示例："查交个朋友直播间的粉丝画像"
1. author_search("交个朋友直播间") → author_id
2. author_fans_profile(author_id) → 粉丝画像
```

**模式1b：达人视频分类名称 → 分类值 → 达人筛选**
```
示例："找亲子类达人"
1. author_category_search("亲子") → category_name/category_full_name
2. author_library_custom_search_author(star_category/full_author_category) → 达人列表
```

**模式2：筛选 → 列表 → 详情**
```
示例："找销售额最高的护肤品，看评论"
1. product_library_custom_search_product(category="护肤品", sort="duration_amount") → 列表
2. product_comments(promotion_id) → 评论
```

**模式3：关联查询**
```
示例："交个朋友直播间带货的花西子商品"
1. author_search("交个朋友直播间") + brand_search("花西子") → IDs
2. author_commerce_product_list(author_id, 筛选brand) → 商品列表
```

## 数据理解规范

### 区间值说明

由于平台规范要求：API 返回的销售额、销量等核心指标均为**区间值**，不是精确数字。常见格式如 `"10万-50万"`、`"1000-5000"`、`"100W+"` 等。

**上限规则**（区间超过此值时显示为带 `+` 的上限值）：
- 达人/小店/视频/直播/品牌/品类：
  - 销售额上限：`1000W+`（即 ≥ 1000万 时显示为 `1000W+`）
  - 销量上限：`100W+`（即 ≥ 100万件 时显示为 `100W+`）
- 单个商品对象：
  - 销售额上限：`100W+`
  - 销量上限：`10W+`

**指数说明**：
1. 销量/销售额指数是基于商品成交相关数据综合计算得出
2. 可通过销量/销售额指数比较同一区间销量/销售额的大小，不可直接用于计算同环比数据

### 禁止对区间值做数学计算

⚠️ **任何情况下，禁止对区间值进行加减乘除、求和、取平均或合计操作。** 

原因：
1. 区间值本身包含不确定性，取中位数或端点值均会引入误差
2. 多条目累加会将误差叠加放大，合计结果严重失真
3. `1000万+` 等带 `+` 的截断值根本无法参与准确计算

**正确做法**：
- 直接展示原始区间字符串，不换算为具体数值后相加
- 需要对比或排序时，仅做定性描述（如"A 销售额高于 B"），不输出精确合计
- 若用户明确要求"粗略估算"，可说明取中位数估算并标注"仅供参考，非真实数据"

### 向用户说明数据局限

- 回复中涉及销售额/销量上限时，**必须向用户解释**平台数据的区间值规范和上限，强调上限值并非实际数值，避免用户理解偏差
- 数据为单平台数据，不含私域、线下、其他平台数据
- 制定查询策略时优先在当前会员权限范围内取数；若权限限制导致明显数据缺口（如时间范围被截断、某模块不可访问），如实说明缺口并引导用户升级数据会员


## 版本与更新

当前 skill 版本：`2026-08-27`。

可通过 `GET {CMM_API_BASE_URL}/v1/cmm/api/permission/list?intent=<任务描述>` 查询当前 API Key 可访问的API 列表、最新 skill 版本号。

请求参数与鉴权：
- `intent`：必填 Query 参数，简要描述任务目标和内容。
- `Authorization: Bearer $CMM_API_KEY`

返回字段：
- `group_id`：BI 用户组 ID。
- `rights`：可访问的 API 权限映射。
- `version`：最新 skill 版本号，取下载链接记录创建日期。

## 请求体

- `api`：所选参考文件中的英文 API 名。
- `query`：包含该 API 文档字段的对象。

## 参考文件

根据用户需求选择对应的参考文件：

- **商品相关**（`references/product.md`）：
  - 商品库（自定义找商品）
  - 商品榜单（热销榜/热推榜/直播热销榜/视频热销榜）
  - 商品基础信息、观众画像、成交画像、评论明细
  - 商品关键数据（日明细/周期合计）
  - 商品关联的达人列表、直播列表、视频列表

- **达人相关**（`references/author.md`）：
  - 达人库（自定义找达人/推荐达人）
  - 达人榜单（带货达人榜/涨粉达人榜）
  - 达人基础信息、粉丝画像
  - 达人关键数据（日明细/周期合计）
  - 达人关联的直播列表、视频列表（发布视频/动销视频）
  - 达人带货的商品列表、品类列表、小店列表、品牌列表

- **小店相关**（`references/shop.md`）：
  - 小店库（自定义找小店）
  - 小店榜单（热销小店榜/热销品牌官方小店榜）
  - 小店基础信息、观众画像、成交画像
  - 小店关键数据（日明细/周期合计）
  - 小店关联的达人列表、商品列表、直播列表、视频列表、商品卡列表、品类列表

- **品牌相关**（`references/brand.md`）：
  - 品牌库（自定义找品牌）
  - 品牌榜单（热销品牌榜）
  - 品牌基础信息、观众画像、成交画像
  - 品牌关键数据（日明细/周期合计）
  - 品牌关联的达人列表、小店列表、商品列表、直播列表、视频列表、商品卡列表、品类列表

- **直播相关**（`references/live.md`）：
  - 直播库（自定义找热门直播间）
  - 直播榜单（今日热销带货直播间榜）
  - 直播详情（基础信息/关键数据/商品列表/观众画像）
  - 直播过程信息（场观明细/互动弹幕/高光讲解）
  - 直播弹幕明细

- **视频相关**（`references/video.md`）：
  - 视频库（自定义找热门视频）
  - 带货视频库（自定义找热销视频）
  - 千川投放素材库（自定义找跑量素材）
  - 视频榜单（热销带货视频榜/热销图文带货视频榜/热门视频榜）
  - 视频详情（数据指标/视频信息/视频脚本/视频评论）
  - 全网趋势热点

- **视频工具**（`references/video-tools.md`）：
  - 提取单条视频的口播文案
  - 拆解单条视频的分镜结构
  - 理解一个或多个视频的画面内容，可附加自定义分析要求
  - 文案和分镜支持视频链接或蝉妈妈视频 ID；画面理解使用视频链接列表

- **品类相关**（`references/category.md`）：
  - 品类分析（按自定义商品关键词查询/按商品分类名称查询）

- **通用搜索**（`references/common.md`）：
  - 商品分类搜索（名称 → category_id）
  - 达人视频分类搜索（名称 → category_name/category_full_name）
  - 商品搜索（名称/抖音链接 → promotion_id）
  - 达人搜索（名称 → author_id）
  - 小店搜索（名称 → shop_id）
  - 品牌搜索（名称 → brand_code）
  - 视频搜索（标题/抖音链接 → aweme_id）