Tencentads Creatives

腾讯广告 - 创意管理

前置依赖：需安装 tencentads-cli（Node.js ≥ 20）。执行 npm install -g tencentads-cli@latest 安装或升级；版本过低时 tencentads 会给出提示。

管理腾讯广告展示广告的动态创意（组件化创意）。

重要提示: 本技能基于腾讯广告营销 API（api.e.qq.com）API v3.0 展示广告接口。

• 以本文档和官方文档为准: 字段名称、参数结构可能与旧版或其他广告平台不同，请勿依赖旧经验。
• 串行执行约束: 同一广告组下，创意的新建、更新和删除操作必须串行执行，不可并发。
• 禁止修改用户意图: 用户明确指定的参数值必须原样传递，严禁静默修改或忽略。若用户要求的参数值脚本不支持，必须明确报错告知用户，不得擅自使用默认值替代。

⚠️ 跨平台 JSON 参数传递规则（经实测验证）

脚本调用格式为 node scripts/<脚本名>.mjs '<JSON参数>'，但 JSON 参数的引号包裹方式因操作系统/终端而异，传递不当会导致 JSON.parse 报错（如 Expected property name or '}' in JSON at position 1）。

⛔ PowerShell 5.x 是重灾区：单引号 '...'、反引号 `" 、反斜杠 \" 三种常见写法**全部失败**（双引号会被吞掉）。必须使用 --% 停止解析符或 \`" 组合转义。 ⛔ Windows CMD 不支持单引号包裹字符串，单引号会被当作普通字符传入脚本，导致 JSON 解析失败。

脚本列表

工作流零：素材准备（可选）

若用户已有 image_id / video_id / component_id，直接跳到工作流一。

当用户需要上传新素材或查找现有素材时，按以下方式操作。

上传新素材

# 上传图片
node scripts/upload-image.mjs '{"account_id":"123456789","file_path":"/tmp/banner.jpg"}'

# 上传视频
node scripts/upload-video-svp.mjs '{"account_id":"123456789","file_path":"/tmp/ad.mp4"}'

返回 image_id / video_id。视频上传后需转码，可用 get-videos.mjs 轮询 system_status 确认转码完成（MEDIA_STATUS_VALID）后再创建创意。

文件格式限制：图片 jpg/png/gif（≤10MB，GIF ≤5秒）；视频 mp4/mov/avi（≤100MB，微信广告需 Progressive 扫描）。

详细接口规范：素材接口文档

查询已有素材

提供两种查询方式，根据用户需求选择：

方式一：素材库模式查询（推荐）

按素材粒度查询单图/视频，支持可用性过滤（比例+宽高+时长）、报表排序、标签/首发/相似度等筛选。

# 查询 16:9 可用视频，按消耗排序
node scripts/get-integrated-media.mjs '{"account_id":"123456789","type":"VIDEO","sort":"cost","ratios":["16:9"],"ratio_valids":[{"ratio":"16:9","file_size_kb_limit":102400,"min_width":1280,"min_height":720,"min_duration":6,"max_duration":900}]}'

# 按名称模糊搜索图片
node scripts/get-integrated-media.mjs '{"account_id":"123456789","type":"IMAGE","fuzzy_name":"产品主图"}'

详细参数说明：integrated-media-get.md

方式二：组件模式查询（用于选择已有组件）

按组件粒度查询，支持按消耗/曝光/ROI 排序，支持起量潜力/首发/低质等筛选。返回 component_id 可直接用于 creative_components。

# 查询视频组件，按消耗排序
node scripts/get-integrated-components.mjs '{"account_id":"123456789","component_sub_types":["VIDEO_16X9","VIDEO_9X16"],"sort_field":"report.cost","sort_type":"DESCENDING"}'

# 查询高潜图片组件
node scripts/get-integrated-components.mjs '{"account_id":"123456789","component_sub_types":["IMAGE_16X9"],"potential_status":["COMMON_POTENTIAL_STATUS_HIGH"]}'

详细参数说明：integrated-components-get.md

查询妙思版权音频

node scripts/get-audios.mjs '{"account_id":"123456789"}'

工作流零B：商品模版生成素材（可选）

当需要使用商品库素材时，可通过商品模版生成图片或视频。此流程是独立的素材生产流程，与广告组类型无关——只要账户有可用的 product_catalog_id 即可使用，生成的 image_id / video_id 是通用素材资产，可用于任意广告组的创意。

判断标识：get-creative-templates.mjs 输出中若包含 support_mpa_image_template: true，则图片组件支持商品模版；support_mpa_video_template: true，则视频组件支持商品模版。

MPA 广告组约束：若广告组为 MPA 模式（mpa_spec 非空），则该广告组的 image/video 组件只能通过商品模版生成，不支持本地上传素材。此约束仅适用于 MPA 广告组内部，不影响商品模版功能本身的使用范围。

参数来源

图片模版流程

1. 从 get-creative-templates.mjs 输出中确认 support_mpa_image_template: true，并获取 image 组件的尺寸要求
2. 查询可用图片模版：

   node scripts/dynamic-product-templates/get-dynamic-ad-image-templates.mjs '{"account_id":"123","product_catalog_id":456,"product_mode":"MULTIPLE","dynamic_ad_template_width":1280,"dynamic_ad_template_height":720}'
   

3. 展示模版列表供用户选择（或仅有一个时自动选中）
4. 用户选择模版后，生成图片：

   node scripts/dynamic-product-templates/generate-dynamic-ad-image.mjs '{"account_id":"123","product_catalog_id":456,"product_mode":"MULTIPLE","product_source":"789","dynamic_ad_template_id":12345,"dynamic_ad_template_size":"SIZE_1280_720"}'
   

5. 返回的 image_id 用于 creative_components 中 image/image_list 等组件

视频模版流程

1. 从 get-creative-templates.mjs 输出中确认 support_mpa_video_template: true
2. 查询可用视频模版（需传入创意形式 template_id）：

   node scripts/dynamic-product-templates/get-dynamic-ad-video-templates.mjs '{"account_id":"123","product_catalog_id":456,"adcreative_template_id":720,"product_mode":"MULTIPLE"}'
   

3. 展示模版列表供用户选择
4. 用户选择模版后，生成视频：

   node scripts/dynamic-product-templates/generate-dynamic-ad-video.mjs '{"account_id":"123","product_catalog_id":456,"product_mode":"MULTIPLE","product_source":"789","dynamic_ad_template_id":67890}'
   

5. 返回的 video_id 用于 creative_components 中 video 组件（video_preview_image_id 可作为 cover_id）

注意：

• 生成的 image_id / video_id 后续流程与普通素材完全一致——传入 creative_components 对应组件的 value 即可
• 若 product_source 为空（mpa_spec.product_series_id 和 marketing_asset_outer_sub_id 均无值），需传 0

详细接口规范：动态商品模版接口文档

工作流一：创建创意

第一步：确认 adgroup_id 并查询广告组上下文

adgroup_id 必须由用户提供，或在上下文中已知。

每次创建创意前，必须先查询广告组上下文，帮助理解广告组的信息：

node scripts/query-adgroup-context.mjs '{"account_id":"123456789","adgroup_id":987654321}'

第二步：查询创意形式及组件联动约束

始终执行以下命令获取可用创意形式列表（含 live_promoted_type_list）：

node scripts/get-creative-template-list.mjs '{"account_id":"123456789","adgroup_id":987654321}'

live_promoted_type 填写规则（live_promoted_type_list 来自上述命令输出）：

• 若 live_promoted_type_list 不为空 → 必须填写 live_promoted_type（顶层参数，与 creative_components 同级）：
  • 默认填 LIVE_PROMOTED_TYPE_SHORT_VIDEO（落地页为视频号直播间、视频号主页等均用此值）
  • 仅当用户明确要求"直播实时画面"（推广内容本身是直播流）时 → 填 LIVE_PROMOTED_TYPE_NATIVE_VIDEO
  • ⚠️ 注意：落地页类型是 PAGE_TYPE_WECHAT_CHANNELS_WATCH_LIVE 不代表 NATIVE_VIDEO，仍填 SHORT_VIDEO
• 若 live_promoted_type_list 为空/null → 不填此字段

若用户指定了 creative_template_id，须确认该 ID 在上述返回列表中，不在则拦截并告知用户。若使用默认（template_id=0，不指定创意形式），则跳过此验证。

始终执行以下命令获取组件列表摘要（若用户未指定 creative_template_id，默认使用 template_id=0，不指定创意形式，required=false 的可选组件默认不加）：

⚠️ 可选组件规则：required=false 的组件（如浮层 floating_zone/floating_zone_list、标签 label、社交互动 social_skill、数据外显 show_data 等）未经用户许可禁止自行构建和添加。仅在用户明确要求该组件时才加入。

node scripts/get-creative-templates.mjs '{"account_id":"123456789","adgroup_id":987654321}'

对结果中所有 has_depend=true 的组件，逐一调用以下命令查询联动约束：

node scripts/get-component-depends.mjs '{"account_id":"123456789","adgroup_id":987654321,"component_type":"WECHAT_CHANNELS"}'

若 depends 为空数组，说明该组件无联动约束，可直接填写。若命令返回失败或 Mock not found，忽略该错误，直接跳到第三步继续。

监测链接（impression_tracking_url / click_tracking_url）

若 get-creative-templates.mjs 输出包含 support_impression_tracking_url: true 或 support_click_tracking_url: true，说明该创意形式支持第三方监测链接，用户提供时将其作为顶层参数传入后续脚本。详见 dynamic-creatives-add.md。

小游戏落地页监测链接（mini_game_tracking_parameter）

与上方顶层监测链接不同，mini_game_tracking_parameter 是小游戏落地页（PAGE_TYPE_WECHAT_MINI_GAME）专属字段，位于 wechat_mini_game_spec 内部。用户描述落地页时若提供了"监测链接"（如 ?state=xxx、?gameplay_concept=1），必须将其填入对应 jump_info 的 page_spec.wechat_mini_game_spec.mini_game_tracking_parameter。

• 适用组件：main_jump_info、action_button、text_link、mini_card_link 等所有包含小游戏落地页的 jump_info
• 同一广告下所有小游戏落地页的 mini_game_tracking_parameter 应保持一致（使用用户提供的值）

关键：component_depends/get 响应中，target_options[].support_options[].value 是该字段唯一合法的枚举值，必须直接使用，不可凭经验填写其他枚举名。例如 show_data.conversion_data_type 的值只能取 support_options 中列出的（如 CONVERSION_DATA_ADMETRIC），而非 CONVERSION_DATA_TYPE_CONVERSION 等臆测值。

第三步：通过组件库获取 component_id

第二步的摘要输出中，每个组件包含 sub_types 字段（如 ["BRAND"]、["VIDEO_16X9","VIDEO_9X16",...]）。如用户未提供 component_id，调用以下命令按组件子类型查询账户下可用组件：

node scripts/get-component-list.mjs '{"account_id":"123456789","component_sub_types":["BRAND"]}'

• component_sub_types 填对应组件的 sub_types 值，同类型有多个 sub_type 时一次性全部传入（如 ["BRAND","BRAND_WECHAT_CHANNEL"]），不要拆开多次调用
• list 为空时：说明 integrated_list 无数据，改用 get-components.mjs fallback 查询：

  node scripts/get-components.mjs '{"account_id":"123456789","component_type":"BRAND"}'
  

  若仍为空，才告知用户该类型组件不存在。
• 查询失败时（返回错误或 Mock not found）：立即跳过，不重试，不换参数重试。已成功获取其他组件的 component_id 时，直接用已有数据继续执行创意创建；若所有必填组件均无法获取，才告知用户。
• 严禁用 0、null、-1 等无效值占位 component_id：查询失败的组件条目整体省略，不填虚假 ID。
• video 组件查询失败时：绝对不可生成 [{}]（空对象数组）——这会让 API 收到无效的空视频条目。查询失败时直接整体省略 video，或告知用户提供视频 ID。
• image_showcase / video_showcase 是复合展示位，value 内嵌套 image/video + image_list，不能拆成独立组件分别传入。详见 references/creative-components.md

通用选择规则（适用于所有组件类型）

获取到组件列表后，按以下规则决策，严禁随机取第一个：

1. 用户已明确指定（提供了名称、ID 或描述）→ 从列表中匹配，使用用户指定的
2. 列表只有一个可用 → 直接使用，无需确认
3. 列表有多个，但用户意图可唯一确定（如视频号场景下只有一个 wechat_channels 型 brand）→ 直接使用
4. 列表有多个，无法从上下文确定 → 询问用户，列出名称（component_custom_name）让用户选择，不可自行决定

若用户提供了 component_id 但查询结果中不存在该 ID，应立即告知用户，不可继续使用该 ID 创建。

brand 组件的类型过滤

get-component-list.mjs 返回的 brand 条目含 brand_type 字段，是第3条"意图可唯一确定"判断的依据：

先按当前投放场景过滤出匹配 brand_type 的组件，再套用上方通用规则。过滤后为空时，告知用户当前场景下无对应类型品牌组件，询问如何处理。

wechat_channels 自动推断

wechat_channels 组件（视频号账号）完全由脚本自动处理，禁止 Agent 在 creative_components 中传入 wechat_channels 键。脚本会按以下路径自动推断：

1. 广告组上下文（优先）：自动调用 adgroups/get 获取 marketing_asset_outer_spec.marketing_asset_outer_id（v2_xxx@finder 格式）；也可通过 adgroup_context 参数传入
2. brand inline value：若 brand 以 inline value 传入且 jump_info.page_type == PAGE_TYPE_WECHAT_CHANNELS_PROFILE，从 wechat_channels_profile_spec.username 提取
3. brand 携带 wechat_channels_username 临时字段：直接使用
4. 以上均无时，调用 wechat_channels_accounts/get 获取账号列表，自动选择（多账号时先结合 video_id 过滤，再结合名称匹配消歧）

多账号消歧：当用户在品牌组件中指定了视频号名称（如"视频号profile页（视频号名称: A+肖像摄影门店）"），Agent 应在 brand 的 inline value 中携带 wechat_channels_account_name 临时字段，脚本会用它在多个可用账号中精确匹配。

⚠️ 禁止手动填写以下字段（全部由脚本自动处理）：

• wechat_channels 组件本身：❌ 不要在 creative_components 中包含 wechat_channels 键，脚本自动生成
• wechat_channels_account_id（export/xxx 格式）：脚本自动从 brand profile_spec 或 API 获取并补全
• finder_object_visibility：脚本根据是否存在 export/ 账号自动决定是否添加
• live_promoted_type：顶层参数（与 creative_components 同级），❌ 禁止写入 wechat_channels.value

第四步A：构建参数并预校验

组装好 creative_components 后，先调用 build-creative-params.mjs 进行预处理和校验（不发起创建）：

node scripts/build-creative-params.mjs '{
  "account_id": "123456789",
  "adgroup_id": 987654321,
  "live_promoted_type": "LIVE_PROMOTED_TYPE_SHORT_VIDEO",
  "creative_components": {
    "video":         [{ "component_id": 1905866436402 }],
    "brand":         [{ "component_id": 1895897993168 }],
    "description":   [{ "value": { "content": "限时优惠，立即了解" } }],
    "action_button": [{ "value": { "button_text": "查看详情", "jump_info": { "page_type": "PAGE_TYPE_OFFICIAL", "page_spec": { "official_spec": { "page_id": 3767098217 } } } } }],
    "main_jump_info":[{ "value": { "page_type": "PAGE_TYPE_OFFICIAL", "page_spec": { "official_spec": { "page_id": 3767098217 } } } }]
  }
}'

处理输出结果：

• errors 非空 → 参数有问题，逐项修正后重调此脚本，不得直接进入创建步骤
• warnings 非空 → 向用户说明，确认后继续（如自动补全失败、cover_id 未查到等）
• errors 为空 → 继续第四步B，将 params 直接传给 create-creative.mjs

字段传递规则：

字段	用户未指定时	用户明确指定时	说明
delivery_mode	脚本默认 DELIVERY_MODE_COMPONENT	必须传入用户指定的值（如DELIVERY_MODE_CUSTOMIZE）	用户说"自定义创意"→传CUSTOMIZE，"组件化创意"或不提→不传
dynamic_creative_type	根据creative_template_id自动推断（0→PROGRAM，>0→COMMON）	必须传入用户指定的值（如DYNAMIC_CREATIVE_TYPE_PROGRAM）	用户说"自动匹配"/"程序化"→传PROGRAM，"指定创意形式"→传COMMON
dynamic_creative_name	脚本自动生成	传入用户提供的名称	未提供时不传，由脚本生成
wechat_channels	脚本自动推断	禁止 Agent 传入，由脚本处理	无论从 brand 还是广告组上下文推断
video.cover_id	自动查询补全	传入用户指定的 cover_id	未提供时脚本自动查询
impression_tracking_url / click_tracking_url	不传	原样透传用户提供的值	校验长度不超过 1024 字符
smart_delivery_spec	脚本自动从广告组获取	传入用户选择的商品 ID	全店托管场景必填
configured_status	不传（由系统默认）	必须传入用户指定的值	用户说"状态：有效"→传AD_STATUS_NORMAL，"状态：暂停"→传AD_STATUS_SUSPEND
auto_derived_program_creative_switch	不传	传入用户指定的开关值	true 开启自动衍生
program_creative_info	【不支持】	【当前不支持】传入会报错	需根据素材动态生成，暂不支持用户传入
site_set_validate_model	不传	传入用户指定的校验模式	如 SITE_SET_VALIDATE_MODEL_STRICT
page_track_url	不传	原样透传用户提供的值	校验长度不超过 1024 字符

关键原则：用户明确指定了参数值（如"投放模式：自定义创意"、"动态创意类型：自动匹配"），Agent 必须将该值传入 build-creative-params.mjs，不要依赖脚本默认值。

第四步B：发起创建

创意数量上限：每个广告组下最多创建 100 个创意（仅自定义创意允许 1000）。create-creative.mjs 在发起创建前会自动查询已有创意数量，超限时拦截并返回错误，无需 Agent 额外处理。若用户遇到上限提示，应引导其先删除部分已有创意后重试。

将第四步A输出的 params 直接传入 create-creative.mjs：

node scripts/create-creative.mjs '<第四步A输出的 params JSON>'

⚠️ 文案含引号时：改用 heredoc 方式（引号无需转义）：

node scripts/create-creative.mjs <<'EOF'
{
  "account_id": "123456789",
  "adgroup_id": 987654321,
  "creative_components": {
    "description": [{ "value": { "content": "别再夸"聪明"，要夸这一点" } }]
  }
}
EOF

组件 value 字段填写原则：

• 内联 value 时，严格按用户为该组件明确提供的信息填写，不得从其他组件的参数推断/复制字段
• 只传用户明确指定的字段，多余字段即使看似合理也应省略
• 组件可用字段以 get-creative-templates 输出的 fields 为准，未在 fields 中列出的字段不得填写
• 中文名到字段名映射：用户用中文描述组件（如"多卡轮播"、"卖点图"）时，在 creative-components.md 的「常用组件类型」表格 中根据「中文名」查找对应的「组件类型」（即字段名）

jump_info 嵌套结构说明：

所有包含跳转链接的组件（action_button, brand, mini_card_link 等）的 jump_info 字段采用 page_type + page_spec.<spec名> 嵌套结构，不能平铺。

• ✅ 正确：{ "page_type": "PAGE_TYPE_OFFICIAL", "page_spec": { "official_spec": { "page_id": 123 } } }

page_type → page_spec 完整映射（含每种 page_type 的 page_spec 结构示例）见 references/enums.md。

creative_components 格式规则及各组件详解见 references/creative-components.md。

dynamic_creative_name 命名规则：

• 用户明确提供了创意名称 → 传入该名称
• 用户未提供 → 无需传入，脚本自动生成含北京时间时间戳的默认名

返回（成功）: { "success": true, "dynamic_creative_id": 8362490722 }

接口详情见: references/dynamic-creatives-add.md

工作流二：更新创意

第一步：获取创意当前完整信息

dynamic_creative_id 必须由用户提供，或在上下文中已知。

无论用户描述了哪些组件，都必须先调用以下命令查询创意当前状态：

node scripts/get-creative.mjs '{"account_id":"123456789","dynamic_creative_id":111222333}'

返回的 creative.creative_components 即为当前完整结构，更新时须以此为基础修改（全量覆盖）。用户只描述了要改哪些组件，其余组件必须从此处获取后原样保留。

第二步：更新

注意：creative_components 为全量覆盖，需基于第一步获取的完整结构修改，不可只传要变更的部分。

如何从 GET 结果构造更新参数：

GET 接口返回的每个组件格式为 { "component_id": xxx, "value": {...}, "is_deleted": false }。

传给 update 接口时，规则如下：

1. 未更改的组件：保留 component_id 和 is_deleted 字段，去掉 value，原样传入
2. 需要用组件库中已有组件替换的：传 { "component_id": 新ID }（无 is_deleted）
3. 需要用全新参数（inline value）更新的组件：用 { "value": {...} } 格式传入
4. jump_info 字段：GET 返回中可能包含 jump_info 顶层组件，不要将其传入 update，跳转信息已包含在 main_jump_info 中

node scripts/update-creative.mjs '{
  "account_id": "123456789",
  "dynamic_creative_id": 111222333,
  "creative_components": {
    "video":         [{ "component_id": 1905866436402 }],
    "brand":         [{ "component_id": 1895897993168 }],
    "description":   [{ "component_id": 1895897993169 }],
    "action_button": [{ "value": { "button_text": "立即咨询", "jump_info": { "page_type": "PAGE_TYPE_WECHAT_CONSULT", "page_spec": { "wechat_consult_spec": { "page_url": "https://work.weixin.qq.com/xxx" } } } } }],
    "main_jump_info": [{ "component_id": 1906127499786 }]
  }
}'

返回（成功）: { "success": true, "dynamic_creative_id": 111222333 }

接口详情见: references/dynamic-creatives-update.md

其他操作（删除）

删除创意

串行执行：同一广告组下创意的新建、更新、删除不可并发。

node scripts/delete-creative.mjs '{
  "account_id": "123456789",
  "dynamic_creative_id": 111222333
}'

接口详情见: references/dynamic-creatives-delete.md

工作流三：素材标签管理

素材标签（material_labels）用于把一组图片/视频素材聚合成"标签包"，便于素材组织与检索。本 skill 提供 查询 / 新建 / 更新 / 绑定 4 个标签接口。

调用示例、参数 schema、字段约束、枚举值、错误码处理详见 references/material-labels.md。

接口文档索引

相关技能

• tencentads-adgroups - 管理广告组（创意需关联到广告组，创建前先获取 adgroup_id）