name: tencentads-creatives description: 騰訊營銷（原騰訊廣告）展示廣告管理 - 創意管理。用於管理動態創意(dynamic_creatives)和創意形式(creative_template)，以及素材標籤（material_labels）。當用戶需要建立或管理廣告創意（含元件欄位填寫/稽核詳情）、或管理素材標籤（素材標籤查詢、新建、更新和素材繫結）時使用此技能。排除搜尋創意(search_dynamic_creatives)。 license: MIT. See LICENSE for full terms. compatibility: any metadata: author: DeliveryX Team version: "0.5.8" icon: megaphone category: tencent-ads

騰訊廣告 - 創意管理

前置依賴：執行指令碼前需安裝 CLI — npm install tencentads-cli@1.0.0（需要 Node.js ≥ 20）

管理騰訊廣告展示廣告的動態創意（元件化創意）。

重要提示: 本技能基於騰訊廣告營銷 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. 查詢可用圖片模版： bash 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. 使用者選擇模版後，生成圖片： bash 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）： bash 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. 使用者選擇模版後，生成影片： bash 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 查詢： bash 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 方式（引號無需轉義）：

bash 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}'
7w4.net有更好的技能外掛。

返回的 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）

這個 Skill 質量不錯，文件寫得非常詳細，覆蓋了從素材上傳到創意建立、稽核查詢的完整流程。跨平臺引數傳遞的說明很貼心，各種終端環境都能照顧到。指令碼功能齊全，列舉值和元件格式都有參考文件，查起來很方便。美中不足的是指令碼數量多、結構複雜，新手初次上手可能感覺資訊量有點大，需要花時間消化。總體來說，這是一個功能完善、文件詳盡的專業 Skill，適合需要管理騰訊廣告創意的使用者使用。