\r \r

ZingAPI 创意列表查询\r

\r 本 skill 用于调用 ZingAPI 的创意列表查询接口，并将自然语言检索需求转换为稳定的接口请求。\r \r 接口地址：\r \r POST https://openapi.dataideaglobal.com/zingapi/v1/creative/list/{customer_name}\r \r 固定请求头：\r \r x-zf-action: creative-list\r \r

凭证要求\r

\r 调用接口前必须配置以下环境变量：\r \r

• ZINGAPI_ACCESS_KEY_ID\r
• ZINGAPI_ACCESS_KEY_SECRET\r
• ZINGAPI_CUSTOMER_NAME\r \r 如任一变量缺失，应先提示用户完成配置。不得在回复、日志或错误信息中展示密钥明文。\r \r

使用方式\r

\r 所有接口请求均通过 scripts/creative_list.py 执行。常规查询优先使用脚本参数；需要完整控制入参时，可使用 JSON 请求体。\r \r 示例：查询最近 30 天美国 Facebook 渠道的游戏视频创意，并返回 AI 标签。\r \r

python scripts/creative_list.py `\r
  --app-type 游戏 `\r
  --geo 美国 `\r
  --platform Facebook `\r
  --creative-type 视频 `\r
  --seen-days 30 `\r
  --sort 最新 `\r
  --include-ai-tags\r
```\r
\r
示例：使用原始 JSON 请求体。\r
\r
```powershell\r
python scripts/creative_list.py --body '@request.json' --output summary\r
```\r
\r
示例：仅检查请求体与签名头，不发送真实请求。\r
\r
```powershell\r
python scripts/creative_list.py --app-type 游戏 --keyword puzzle --dry-run\r
```\r
\r
## 参数转换规范\r
\r
根据用户描述转换为脚本参数时，遵循以下规则：\r
\r
- 完整入参映射见 `references/input-mapping.md`。当用户描述命中该映射表中的字段，但脚本没有对应的专用命令行参数时，应生成 JSON 请求体，并使用 `python scripts/creative_list.py --body '@request.json'` 调用。\r
- 行业类型：`游戏`、`工具`、`电商` 分别对应 `app_type` 的 `1`、`2`、`3`。\r
- 素材类型：`图片`、`视频`、`轮播`、`HTML`、`试玩` 分别对应 `ads_type` 的 `1`、`2`、`3`、`4`、`7`。\r
- 国家/地区：中文国家名应转换为三位国家/地区编码，例如 `美国` 转为 `USA`，`日本` 转为 `JPN`。\r
- 排序方式：`最新`、`展现`、`热度`、`最后发现`、`投放天数`、`点赞`、`评论`、`分享` 分别转换为对应的 `sort_field`。\r
- 去重方式：`广告去重`、`素材去重`、`广告主去重` 分别对应 `duplicate_removal` 的 `0`、`1`、`2`。\r
- 页码默认值为 `page=1`；每页数量默认值为 `page_size=20`，最大值为 `20`。\r
- 用户未指定时间范围时，默认查询最近 7 天。\r
- 用户要求“返回 AI 标签”或“带 AI 标签”时，添加 `--include-ai-tags`。\r
\r
## 执行流程\r
\r
1. 识别用户的检索目标、行业、地区、渠道、素材类型、时间范围和排序方式。\r
2. 若关键条件缺失但可使用默认值，应直接采用默认值；仅在业务目标无法判断时再询问用户。\r
3. 使用 `scripts/creative_list.py` 发起请求。\r
4. 默认返回摘要结果；仅当用户明确要求完整响应时使用 `--output raw`。\r
5. 错误处理时保留 `trace_id`，便于接口问题排查。\r
6. 如后续需要查询创意详情，应保留结果中的 `ad_key`、`app_type` 和 `search_flag`。\r
\r
## 输出字段\r
\r
默认摘要结果按业务含义分组展示，包括：\r
\r
- `广告主`：广告主名称、ID 或域名、开发者、Logo、分类。\r
- `素材`：素材类型、预览图、资源列表、视频时长、素材 ID、NSFW 标记。\r
- `投放`：行业、渠道、国家地区、文案语言、首次投放时间、最后发现时间、投放天数。\r
- `指标`：人气总值、当周人气值总和、展现估值、热度值、关联广告数、互动数据。\r
- `文案`：标题、正文、Message、CTA。\r
- `链接`：落地页、原帖链接、结束卡片或关联视频。\r
- `游戏标签`：游戏核心赛道、游戏 IP、游戏玩法、游戏主题。\r
- `AI素材标签`：图片、视频及新版 AI 标签。
- `原始字段`：保留关键原始字段，便于二次查询和排查。

字段含义以 `references/response-fields.md` 为准。用户要求展示“人气值”时，应使用 `指标.人气总值` 或 `指标.当周人气值总和`；不得将 `指标.热度值` 作为人气值展示。
摘要结果会将渠道、国家/地区等字典编码转换为“名称 (编码)”格式。人气值、热度值、展现估值等较大数值会使用 `K`、`M`、`B` 缩写并保留一位小数；原始编码和原始数值保留在 `原始字段` 中。

当 `is_nsfw` 为 `true` 时，素材资源地址可能被隐藏或替换为默认图片。
\r
## 参考资料\r
\r
- 参数说明见 `references/parameters.md`。\r
- 完整入参映射见 `references/input-mapping.md`。\r
- 出参字段说明见 `references/response-fields.md`。\r
- 配置与调用示例见 `references/examples.md`。\r