← 返回目录
📁 API Reference › Ads

获取广告

您可以使用本接口获取普通广告及智能创意广告的相关信息。

若想获取智能创意广告的素材，需使用/ad/aco/get/接口。

注意
如果需要查询删除的广告数据（包括推广系列和广告组)，可以设置 primary_status字段的值为STATUS_DELETE或者设置 secondary_status字段的值为 AD_STATUS_CAMPAIGN_DELETE/ AD_STATUS_ADGROUP_DELETE/AD_STATUS_DELETE。系统默认不查询删除的数据。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{30%}|v1.2{35%}|v1.3{35%}| |---|---|---| |接口路径|/v1.2/ad/get/|/v1.3/ad/get/| |请求参数名称|create_start_time<br>create_end_time<br>status|creation_filter_start_time<br>creation_filter_end_time<br>secondary_status| |请求参数类型|advertiser_id: number<br>campaign_ids: number[]<br>adgroup_ids: number[] <br>ad_ids: number[] |advertiser_id: string <br>campaign_ids: string[]<br>adgroup_ids: string[] <br>ad_ids: string[] | |废弃请求参数|/|ad_text<br>billing_events| |新增请求参数|/ |exclude_field_types_in_response<br>destination<br>creative_material_mode<br>optimization_goal<br>campaign_system_origins<br>buying_types<br>modified_after<br>campaign_automation_type<br>ad_ids_v2| |返回参数名称|status<br>opt_status<br>profile_image<br>open_url<br>open_url_type<br>vast_moat<br>is_creative_authorized<br>dpa_fallback_type<br>dpa_open_url_type<br>dpa_video_tpl_id|secondary_status<br>operation_status<br>profile_image_url<br>deeplink<br>deeplink_type<br>vast_moat_enabled<br>creative_authorized<br>shopping_ads_fallback_type<br>shopping_deeplink_type<br>shopping_ads_video_package_id| |返回参数类型|advertiser_id: number<br>campaign_id: number<br>adgroup_id: number <br>ad_id: number <br>tiktok_item_id: number<br>card_id: number |advertiser_id: string <br>campaign_id: string<br>adgroup_id: string <br>ad_id: string<br>tiktok_item_id: string<br>card_id: string | |废弃返回参数|/|premium_badge_id| |新增返回参数|/ |product_specific_type<br>catalog_id<br>item_group_ids<br>product_set_id<br>sku_ids<br>dynamic_format<br>vertical_video_strategy<br>dynamic_destination<br>brand_safety_vast_url<br>viewability_postbid_partner<br>viewability_vast_url<br>utm_params<br>key<br>value<br>showcase_products（包括该对象内的参数）<br>tracking_app_id<br>tracking_offline_event_set_ids<br>music_id<br>carousel_image_index<br>tiktok_page_category<br>phone_region_code<br>phone_region_calling_code<br>phone_number<br>deeplink_format_type<br>campaign_system_origin<br>deeplink_utm_params<br>cpp_url<br>aigc_disclosure_type<br>tracking_message_event_set_id<br>auto_message_id<br>campaign_automation_type<br> smart_plus_ad_id<br>ad_ids_v2<br>creative_auto_enhancement_strategy_list`|


# 请求

**地址**  https://business-api.tiktok.com/open_api/v1.3/ad/get/

**方法** GET

**Header**

```xtable
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。 |

参数

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_id {必填}|string|广告主 ID。|
|fields |string[]| 返回字段。查看返回中`list`下的字段，获取您可以指定的字段。如果您不传入该字段，系统将默认返回所有字段。|
|exclude_field_types_in_response| string[]|想要从返回中移除的字段种类。<br>允许的枚举值： <ul><li>`NULL_FIELD`: 值为null的字段。</li></ul>|
|filtering |object|筛选条件。<br>示例：`filtering=&#123;"campaign_automation_type":"UPGRADED_SMART_PLUS"&#125;`。|
#| campaign_automation_type | string | 推广系列自动化类型。<br><br>枚举值：<ul><li>`MANUAL`：手动推广系列。</li><li>`SMART_PLUS`：Smart+ 推广系列。</li><li>`UPGRADED_SMART_PLUS`：升级版 Smart+ 推广系列，一种新的自动化推广系列类型。查看[升级版 Smart+ 推广系列](1853452461203458.html)文档，详细了解升级版 Smart+ 推广系列。</li></ul> |
#|campaign_ids |string[]|推广系列 ID，允许数量范围: 1-100。|
#|campaign_system_origins| string[] |广告所属的推广系列来源。<br> <br> 枚举值：<ul><li>`PROMOTE`：该推广系列为通过 TikTok 移动应用创建的内容加热推广系列。</li><li>`TT_ADS_PLATFORM`：该推广系列为通过 API 或TikTok 广告管理平台创建的非内容加热推广系列。</li></ul> 默认值：`&#91;"TT_ADS_PLATFORM"&#93;` 。<br><br>仅支持获取内容加热广告的以下信息：<ul><li>`advertiser_id`</li><li>`campaign_id`</li><li> `campaign_name`</li><li>`adgroup_id`</li><li>`adgroup_name` </li><li>`ad_id`</li><li>`ad_name` </li><li> `create_time`</li><li>`operation_status`</li><li>`secondary_status` </li></ul> <br>若想了解支持的内容加热广告功能及广告筛选条件，请查看[内容加热推广系列](1785880454546433.html)。|
#|adgroup_ids |string[]| 广告组 ID，允许数量范围: 1-100。 |
#| ad_ids_v2 | string[] | v2 广告 ID 列表。<br><br>可以筛选的 ID 类型包括：<ul><li>手动广告的 ID。</li><li>升级版 Smart+ 广告的 ID。要通过 API 创建升级版 Smart+ 广告，可使用[升级版 Smart+ 广告 API](1843301794874370.html)。</li></ul><br>最大数量：100。<br><br><p><span style="color:darkred"><b>注意</b></span>：使用升级版 Smart+ 广告的 ID 进行筛选时，返回将仅包含以下参数：</p><ul><li>`advertiser_id`</li><li>`campaign_id`</li><li>`campaign_name`</li><li>`adgroup_id`</li><li>`adgroup_name`</li><li>`ad_id_v2`</li><li>`ad_name`</li><li>`campaign_automation_type`</li></ul> |
#|ad_ids |string[]| 广告 ID 列表，允许数量范围: 1-100。|
#|primary_status |string| 一级状态。见[枚举值 - 一级状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
#|secondary_status|string|广告二级状态。枚举值详见[枚举值 - 二级状态 - 广告状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。<br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>沙箱环境下本字段不返回，因为广告未实际投放。</li><li>请查看[一级状态下所支持的二级状态](https://ads.tiktok.com/marketing_api/docs?id=1757239620352002) ，了解对于所指定的一级状态，您可以传入的`secondary_status` 有效值。</li></ul>|
#|objective_type |string| 推广目标。<br><p>枚举值参见[枚举值-推广目标](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138) 。<br><p><p><span style="color:darkred"><b>注意</b></span>：若您选择`WEB_CONVERSIONS`或`CONVERSIONS`的推广目标作为筛选条件，目前会同时返回以`WEB_CONVERSIONS`或`CONVERSIONS`为推广目标的数据。|
#| buying_types | string[] |购买类型。 <br><br>枚举值：<ul><li>`AUCTION`：竞价广告。</li><li>`RESERVATION_RF`：合约覆盖和频次广告以及 TikTok Pulse 广告。</li><li>`RESERVATION_TOP_VIEW`：合约 TopView 广告。</li></ul><br> 默认值：`&#91;"AUCTION", "RESERVATION_RF"&#93;`。<br><br>若想了解 API 中支持的 TopView 广告功能，请查看[ TopView](1804258360285186.html)。<br><br><p><span style="color:darkred"><b>注意</b></span>： 枚举值 `RESERVATION_TOP_VIEW` 不支持与其他值同时使用。若想筛选 TopView 广告，可将本字段设置为`["RESERVATION_TOP_VIEW"]`。 |
#|optimization_goal|string|优化目标。枚举值见[枚举值-优化目标](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138#item-link-优化目标)。|
#|creative_material_mode|string|创意投放方式。<br>枚举值: `CUSTOM`（自定义）、`DYNAMIC`（程序化）、`SMART_CREATIVE`（智能创意）。|
#| destination | string | 目标页类型。<br>枚举值：<ul><li> `APP`：所推广 App 在Google Play 或 Apple Store 的下载页面。广告对应的广告组中`promotion_type` 设置为`APP_ANDROID` 或 `APP_IOS`。</li><li>`TIKTOK_INSTANT_PAGE`: TikTok 即时体验页面，包括自定义页面、线索表单（即时体验表单）、应用介绍页和即时体验商品页面。广告中指定了TikTok即时体验页面的页面 ID（`page_id`）。</li><li> `WEBSITE`：网站页面。广告中指定了落地页（`landing_page_url`）。</li><li>`SOCIAL_MEDIA_APP`：社交媒体 URL。若想了解支持将目标页面设置为社交媒体 URL 的广告类型，请查看[创建推广对象类型为即时通讯应用的线索广告](1774482999036930.html)。 </li><li> `PHONE_CALL`：电话号码。若想了解支持将目标页面设置为电话号码的广告类型，请查看[创建推广对象类型为电话通话的线索广告](1774482936048641.html)。</li></ul> <br>若您同时指定了`objective_type` ，请查看[推广目标下支持筛选的目标页面类型](https://ads.tiktok.com/marketing_api/docs?id=1764306884771842)，了解本字段可以设置的值。   |
#|creation_filter_start_time |string| 筛选创建时间晚于某一时间的广告，格式为 `YYYY-MM-DD HH:MM:SS`（UTC 时区）。<br><br>建议：为确保任务的成功执行及速度，创建时间的筛选范围建议不超过 6 个月。|
#|creation_filter_end_time |string|筛选创建时间早于某一时间的广告，格式为 `YYYY-MM-DD HH:MM:SS`（UTC 时区）。<br><br>建议：为确保任务的成功执行及速度，创建时间的筛选范围建议不超过 6 个月。|
#| modified_after | string | 筛选修改时间晚于某一时间的广告，格式为 `YYYY-MM-DD HH:MM:SS`（UTC 时区）。<br><br> 建议：为确保任务的成功执行及速度，修改时间的筛选范围建议不超过 6 个月。 |
|page |number|当前页数。<br><br>默认值: 1。取值范围: ≥ 1。|
|page_size |number|分页大小。<br><br>默认值: 10。取值范围: 1-1,000。|

示例

获取升级版 Smart+ 推广系列中的广告（素材组）层级数据

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/ad/get/?advertiser_id={{advertiser_id}}&filtering={"campaign_automation_type":"UPGRADED_SMART_PLUS","ad_ids_v2":["{{ad_id_v2}}"]}' \
//input the ID of an Upgraded Smart+ Ad (Asset Group) through {{ad_id_v2}}
--header 'Access-Token: {{Access-Token}}'
(/code)

获取升级版 Smart+ 推广系列中的素材层级数据

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/ad/get/?advertiser_id={{advertiser_id}}&filtering={"campaign_automation_type":"UPGRADED_SMART_PLUS","ad_ids":["{{ad_id}}"]}' \
//input the ID of an Upgraded Smart+ Creative through {{ad_id}}
--header 'Access-Token: {{Access-Token}}'
(/code)

返回

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number|返回码。完整返回码列表及描述，可见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097) 。|
|message |string|返回信息。更多信息可见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data |object|返回数据。返回列表默认按广告 ID（`ad_id`）倒序排列。  |
#|list |object[]| 广告列表。返回字段根据请求参数中 `fields` 字段产生。如果您不传入该字段，系统将默认返回所有字段。<br><br><p><span style="color:darkred"><b>注意</b></span>：返回中不包含通过 TikTok Shop 创建的商品总交易额最大化广告（[Product GMV max ads](https://ads.tiktok.com/help/article/about-automated-product-ads?lang=zh)）和直播总交易额最大化广告（LIVE GMV max ads）。通过 API 或 TikTok 广告管理平台创建的购物广告则不受影响。|
##|advertiser_id |string| 广告主 ID。 |
##|campaign_id |string| 推广系列 ID。 |
##|campaign_name |string| 推广系列名称。 |
##| campaign_automation_type | string | 推广系列自动化类型。<br><br>枚举值：<ul><li>`MANUAL`：手动推广系列。</li><li>`SMART_PLUS`：Smart+ 推广系列。</li><li>`UPGRADED_SMART_PLUS`：升级版 Smart+ 推广系列。要了解有关升级版 Smart+ 推广系列的更多信息，可参阅[升级版 Smart+ 推广系列](1853452461203458.html)。<ul><li>当 `campaign_automation_type` 为 `UPGRADED_SMART_PLUS` 时，返回的 `ad_id_v2` 是升级版 Smart+ 广告的 ID。</li></ul></li><li>`UPGRADED_SMART_PLUS_CREATIVE`：升级版 Smart+ 推广系列。要了解有关升级版 Smart+ 推广系列的更多信息，可参阅[升级版 Smart+ 推广系列](1853452461203458.html)。<ul><li>当 `campaign_automation_type` 为 `UPGRADED_SMART_PLUS_CREATIVE` 时，返回的 `ad_id` 是升级版 Smart+ 广告（素材组）中某个素材的 ID。</li></ul></li></ul> |
##| campaign_system_origin | string | 仅为内容加热广告返回本字段。<br>非内容加热广告不返回本字段。<br><br>广告所属的推广系列来源。 <br><br>枚举值： <ul><li>`PROMOTE`：该推广系列为通过 TikTok 移动应用创建的内容加热推广系列。</li></ul><br>仅为内容加热广告（推广系列层级`campaign_system_origin` 为 `PROMOTE`）返回以下信息：<ul><li>`advertiser_id`</li><li>`campaign_id`</li><li> `campaign_name`</li><li>`adgroup_id`</li><li>`adgroup_name` </li><li>`ad_id`</li><li>`ad_name` </li><li> `create_time`</li><li>`operation_status`</li><li>`secondary_status` </li></ul>|
##|adgroup_id |string| 广告组 ID。 |
##|adgroup_name|string| 广告组名称。 |
##| smart_plus_ad_id | string | 仅当 `campaign_automation_type` 为 `UPGRADED_SMART_PLUS_CREATIVE` 时返回。<br><br>升级版 Smart+ 广告的 ID。 |
##| ad_id_v2 | string | v2 广告 ID。<br><br><ul><li>当 `campaign_automation_type` 为 `MANUAL` 时，此字段代表手动广告的 ID。</li><li>当 `campaign_automation_type` 为 `SMART_PLUS` 时，此字段代表 Smart+ 推广系列中广告的 ID。</li><li>当 `campaign_automation_type` 为 `UPGRADED_SMART_PLUS` 时，此字段代表升级版 Smart+ 广告的 ID。</li></ul> |
##|ad_id |string| 广告 ID。 <br><br><ul><li>当 `campaign_automation_type` 为 `MANUAL` 时，此字段代表手动广告的 ID。</li><li>当 `campaign_automation_type` 为 `SMART_PLUS` 时，此字段代表 Smart+ 推广系列中广告的 ID。</li><li>当 `campaign_automation_type` 为 `UPGRADED_SMART_PLUS_CREATIVE` 时，此字段代表升级版 Smart+ 广告中素材的 ID。</li></ul>|
##|ad_name |string| 广告名称。 |
##|create_time |string|广告创建时间，格式为 `YYYY-MM-DD HH:MM:SS`（UTC 时区）。|
##|modify_time |string|广告修改时间，格式为 `YYYY-MM-DD HH:MM:SS`（UTC 时区）。|
##|identity_type|string|认证身份类型。枚举值：  `CUSTOMIZED_USER` (自定义用户），`AUTH_CODE` (授权用户)， `TT_USER` (TikTok用户）， `BC_AUTH_TT`（添加到商务中心的TikTok用户）。|
##|identity_id |string|认证身份ID。<br>如果您不使用Spark Ads，传入 `identity_id` 和 `identity_type` (`CUSTOMIZED_USER`类型)可帮助您更好地管理广告信息。|
##|identity_authorized_bc_id|string|与添加到商务中心的TikTok用户这一认证身份绑定的商务中心的ID。当`identity_type` 为 `BC_AUTH_TT`时返回。|
##|catalog_id|string|您为广告选择的商品库 ID。<br><br><p><span style="color:darkred"><b>注意</b></span>：自 2024 年 6 月 30 日起，将不再为新创建的广告组层级 `product_source` 为 `STORE` 的购物广告返回 `catalog_id`，传入的 `catalog_id` 字段将被忽略。存量的 `product_source` 为 `STORE` 的购物广告若未被更新，则不受影响。若您更新存量的这类广告，且广告已绑定 `catalog_id` ，则绑定的 `catalog_id` 将清空且该 `catalog_id` 字段将不再返回。|
##|product_specific_type|string|选择商品的维度。<br><br>枚举值：<ul><li>`ALL`：允许 TikTok 从所有商品中动态选择。</li><li> `PRODUCT_SET`：请选择一个商品系列。TikTok 将动态选择该商品系列中的商品。</li><li>`CUSTOMIZED_PRODUCTS`：选择自定义数量的特定商品。</li></ul>|
##|item_group_ids|string[]|商品的 SPU ID 列表。|
##|product_set_id|string|商品系列 ID。|
##|sku_ids|string[]|商品的 SKU ID 列表。|
##| showcase_products | object[] |您想要用在广告中的橱窗商品列表。<br> 您可查看[创建商品来源为橱窗的视频购物广告](https://ads.tiktok.com/marketing_api/docs?id=1759232259360770)了解详情。 |
###| item_group_id | string | 商品的 SPU ID。 |
###| store_id | string | 商品（`item_group_id`）所属的店铺 ID。<br>请注意本字段仅支持 TikTok Shop 店铺。 |
###| catalog_id | string | 商品（`item_group_id`）所属的商品库 ID。 <br><br><p><span style="color:darkred"><b>注意</b></span>：自 2024 年 6 月 30 日起，将不再为新创建的广告组层级 `product_source` 为 `STORE` 的购物广告返回本字段，传入的 `showcase_products` 对象数组中的 `catalog_id` 字段将被忽略。存量的 `product_source` 为 `STORE` 的购物广告若未被更新，则不受影响。若您更新存量的这类广告，且广告已绑定 `showcase_products` 对象数组中的 `catalog_id`，则绑定的`catalog_id` 将清空且该 `catalog_id` 字段将不再返回。|
##|ad_format |string| 广告样式。枚举值：`SINGLE_IMAGE`， `SINGLE_VIDEO`， `LIVE_CONTENT`, `CAROUSEL_ADS`（非视频购物类型的轮播广告），`CATALOG_CAROUSEL`（视频购物类型的轮播广告） 。|
##|vertical_video_strategy|string|商品销量场景中使用的视频类型。 <br><br>枚举值： `UNSET`（未设置），`SINGLE_VIDEO`（单个视频），`CATALOG_VIDEOS`（使用视频模板的商品库视频），`CATALOG_UPLOADED_VIDEOS`（使用已上传视频的商品库视频）， `LIVE_STREAM`（直播视频）。  |
##|dynamic_format|string|动态样式。<br><br>枚举值：<ul><li>`DYNAMIC_CREATIVE`：智能创意。根据用户的购买意图向每位用户展示不同的视频，商品卡片和目标页面，从而最大限度地提高广告转化量。 </li><li>`UNSET`：未设置。</li></ul>|
##|video_id |string|视频 ID。<br><br>若广告为通过从关联的企业号、创作者授权的帖子或商务中心中创作者授权的账户提取原生视频而创建的 Spark Ads，则本字段值为 null。此时您可以通过`tiktok_item_id`字段获取用作 Spark Ads 的 TikTok 帖子 ID。<br><br>若想了解 Spark Ads 详情，请查看[创建 Spark Ads](1739470744631298.html)。|
##|image_ids|string[]| 图片 ID 列表。 |
##|carousel_image_index|integer |用于指定视频购物类型的轮播广告中要使用的附加图片的索引。<br> 您通过本字段传入的数值代表每个商品库商品的附加图片列表（`additional_image_urls`）中要使用的附加图片的位置。|
##| music_id | string | TikTok轮播广告中使用的音乐的ID。   |
##|tiktok_item_id |string| 用作 Spark Ads 的 TikTok 帖子 ID，<br><br>若想了解 Spark Ads 详情，请查看[创建 Spark Ads](1739470744631298.html)。<br><br><p><span style="color:darkred"><b>注意</b></span>：本字段为以下类型的 Spark Ads 返回：<ul><li>通过 [Spark Ads 提取](https://business-api.tiktok.com/portal/docs?id=1739470744631298#item-link-Spark%20Ads%20%E6%8F%90%E5%8F%96)创建的 Spark Ads。</li><li>通过 [Spark Ads 推送](https://business-api.tiktok.com/portal/docs?id=1739470744631298#item-link-Spark%20Ads%20%E6%8E%A8%E9%80%81)创建且通过广告审核的 Spark Ads。</li></ul>|
##| promotional_music_disabled | boolean |是否关闭推广音乐开关。`true`： 关闭；`false`： 打开。默认`true`。如果您想为TikTok视频开启合拍或跟拍，请将该字段设置为`false`，即打开推广音乐。 |
##|item_duet_status | string | 合拍开关状态。枚举值：`ENABLE`： 打开合拍；`DISABLE`： 禁止合拍。只有在`promotional_music_disabled`设置为`false`时，该字段才有效。|
##| item_stitch_status | string | 跟拍开关状态。枚举值：`ENABLE`： 打开跟拍；`DISABLE`： 禁止跟拍。只有在`promotional_music_disabled`设置为`false`时，该字段才有效。|
##| dark_post_status | string | 表示该视频是否为dark post。枚举值：`ON`，`OFF`。|
##| branded_content_disabled | boolean |默认值为`false`。当`branded_content_disabled`为`true`时，`dark_post_status`将无法被更改。|
##|shopping_ads_video_package_id|string| 商品库视频模板ID。<br data-tomark-pass>当对应的推广系列`objective_type`为`PRODUCT_SALES`时返回该字段。|
##|ad_text |string| 广告文案，将作为广告创意的一部分展示给您的受众，向他们传达您想要推广的信息。关键词匹配类型为精确匹配。 |
##|ad_texts |string[]| 广告文案列表。 |
##|call_to_action|string| 行动引导文案，见 [枚举值-行动引导文案](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)|
##|call_to_action_id|string|行动引导文案素材包ID。行动引导文案素材包指的是一组自动优化的行动引导文案。如果本字段和`call_to_action`都传入，`call_to_action`会被忽略。关于动态优选CTA的更多信息，请参见[智能推荐CTA > 动态优选CTA](https://ads.tiktok.com/marketing_api/docs?id=1740307296329730)。|
##|card_id|string| 创意素材包 ID。|
##|landing_page_url |string|落地页 URL。|
##|utm_params |object[]|URL 参数列表。|
###|key |string| URL 参数。|
###|value |string|URL 参数的值。|
##|page_id |number|页面 ID。 |
##| cpp_url | string | 自定产品页面 URL。<br>自定产品页面是一种定制化的产品页面，支持自定义截图、推广文字和应用预览，可用于突出介绍所推广应用的特定内容或功能，或针对特定受众群体进行推广。 |
##|tiktok_page_category|string|您希望推广的 TikTok 页面的类型。<br><br>枚举值： <ul><li>`PROFILE_PAGE`：TikTok 账号主页。</li><li>`OTHER_TIKTOK_PAGE`：其他 TikTok 页面，包括播放列表页面、话题标签页面、音乐页面和商业化特效页面。</li><li>`TIKTOK_INSTANT_PAGE`：自定义 TikTok 即时体验页面。</li></ul> |
##| phone_region_code | string | 仅当广告组层级 `promotion_type` 设置为 `LEAD_GEN_CLICK_TO_CALL` 时返回。<br><br>受众可点击广告拨打的电话号码的地区代码。 <br><br>若想了解如何创建推广对象类型为电话通话的线索广告，请查看[这里](1774482936048641.html)。 <br><br><p><span style="color:darkred"><b>注意</b></span>：创建推广对象类型为电话通话的线索广告目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。 |
##| phone_region_calling_code | string | 仅当广告组层级 `promotion_type` 设置为 `LEAD_GEN_CLICK_TO_CALL` 时返回。 <br><br>受众可点击广告拨打的电话号码的区号。 <br><br><p><span style="color:darkred"><b>注意</b></span>：创建推广对象类型为电话通话的线索广告目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。 |
##| phone_number | string | 仅当广告组层级 `promotion_type` 设置为 `LEAD_GEN_CLICK_TO_CALL` 时返回。 <br><br>受众可点击广告拨打的电话号码。<br><br><p><span style="color:darkred"><b>注意</b></span>：创建推广对象类型为电话通话的线索广告目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。 |
##| creative_auto_enhancement_strategy_list | string[] | 应用于你的广告的自动优化策略列表。<br>你传入的优化功能将在你的推广系列投放期间自动实时应用。<br><br>枚举值：<ul><li>`VIDEO_QUALITY`：视频质量。通过提高分辨率和清晰度来提升整体视觉效果。</li><li>`MUSIC_REFRESH`：音乐焕新。替换为当前 TikTok 上流行的音乐，紧跟潮流趋势。</li><li>`IMAGE_QUALITY`：图片质量。通过提高分辨率和清晰度来提升整体视觉效果。</li><li>`IMAGE_RESIZE`：调整尺寸。调整图片大小，充分利用全屏功能。</li></ul> |
##|deeplink |string| 深度链接，即已安装应用的用户点击链接后跳转至的特定页面。|
##|deeplink_type |string| 深度链接类型。  <br><br>枚举值：<ul><li>`NORMAL`：非延迟深度链接。</li><li>`DEFERRED_DEEPLINK`：延迟深度链接。</li></ul> |
##| deeplink_format_type | string | 深度链接的格式类型。<br><br>枚举值：  <ul><li>`UNIVERSAL_OR_APP_LINK`：通用/应用链接，即以`http://`或 `https://` 开头的 iOS 通用链接或 Android 应用链接。</li><li>`SCHEME_LINK`：URL 架构，即格式为`scheme://resource` 的自定义网址架构。例如，WhatsApp 的自定义网址架构格式应为`whatsapp://resource`。</li><li>`NONE`：非深度链接。</li></ul> |
##|shopping_ads_deeplink_type|string| 在购物广告中要使用的深度链接的来源。<br><br>枚举值：<ul><li>`NONE`：不设置深度链接。</li><li>`CUSTOM`：自定义深度链接。在广告中使用你提供的深度链接。</li><li>`SHOPPING_ADS`：商品库深度链接。使用商品库中为各商品添加的深度链接。</li></ul>|
##| deeplink_utm_params| object[] | 深度链接 URL 参数列表。<br><br><p><span style="color:darkred"><b>注意</b></span>：在非视频购物广告场景使用 `utm_params` 目前为白名单功能。如需使用此功能，请联系您的 TikTok 销售代表。 |
###| key | string | 深度链接 URL 参数。 |
###| value | string | 深度链接 URL 参数的值。 |
##|shopping_ads_fallback_type|string| 在购物广告再营销场景下，深度链接唤起失败后的返回落地页类型。<br><br>枚举值：<ul><li>`DEFAULT`：未设置。</li><li>`CUSTOM`: 自定义链接。您可以在广告组中提供一个网页地址, 并回退到这个地址。</li><li>`SHOPPING_ADS`：商品库链接。 回退到目录中为各商品添加的网页地址。</li></ul>|
##|fallback_type |string|失败路径。如果用户没有安装过应用，您可以选择让用户回退去安装应用，或者去您想推广的网页。 <br><br>枚举值：<ul><li>`APP_INSTALL`：广告组层级通过 `app_id` 指定的推广应用对应的 App Store 或 Google Play 页面。</li><li>`WEBSITE`：通过 `landing_page_url` 指定的推广网页。</li><li>`UNSET`：未设置。</li></ul> |
##|dynamic_destination|string|动态目标页面策略。<br><br>枚举值：<ul><li>`DLP`：动态落地页。基于用户的主页、行为和意向，向每位用户展示不同的目标页面，包括自定义网站或即时体验商品页面等，从而最大限度地提高广告转化量。</li><li>`UNSET`：未设置。</li></ul>|
##| auto_message_id | string | TikTok 私信广告中使用的自动消息的 ID。<br> 目前唯一支持的自动消息类型为欢迎消息。 |
##| aigc_disclosure_type | string | 是否启用 AI 生成内容自主声明开关，以表明广告中包含 AI 生成内容。启用该开关后，当用户查看完整广告时，您的广告将带有“广告主标记为 AI 生成”的标签。<br><br>枚举值：<ul><li>`SELF_DISCLOSURE`：启用开关，声明广告包含 AI 生成内容。</li><li>`NOT_DECLARED`：不声明广告包含 AI 生成内容。</li></ul> |
##| disclaimer_type | string | 广告中的免责声明类型。枚举值：`TEXT_LINK`（文字链免责声明），`TEXT_ONLY`（纯文本免责声明）。 <br><p><span style="color:darkred"><b>注意</b></span>：免责声明目前对注册地非美国或加拿大且使用竞价推广目标的广告主，以及使用覆盖和频次推广目标的所有广告主为白名单功能。如需使用此功能，请联系您的TikTok销售代表。|
##| disclaimer_text | object | 广告中的纯文本免责声明。 |
###| text | string | 免责声明文案。 |
##| disclaimer_clickable_texts | object[] | 广告中的文字链免责声明。 |
###| text | string | 免责声明文案。 |
###| url | string | 文字链免责声明的URL 。用户点击对应文字时，将打开您提供的对应URL，查看免责声明的详细内容。 |
##|tracking_pixel_id|number|正在监测的 Pixel ID。你可以使用此字段追踪发生在外部网站的事件。|
##|tracking_app_id | string| 正在监测的应用的 ID。|
##| tracking_offline_event_set_ids | string[] | 正在监测的线下事件组 ID 列表。<br>点击[这里](https://ads.tiktok.com/marketing_api/docs?id=1758051319816193)了解如何创建和管理线下事件组。  |
##| tracking_message_event_set_id | string | 即时通讯广告中监测的消息事件集的 ID。 |
##|vast_moat_enabled |boolean| 是否开启Moat（第三方视频可见性监测）。TikTok与Moat合作，为您在TikTok for Business上购买的品牌竞价、覆盖和频次信息流广告提供可见性监测。<br><p><span style="color:darkred"><b>注意</b></span>：若您想开启Moat第三方可见性监测，相较于本字段，更推荐使用`viewability_postbid_partner`，将值设为 `MOAT` 。|
##|viewability_postbid_partner|string|出价后第三方可见性监测合作伙伴。枚举值：`UNSET`，`MOAT`，`DOUBLE_VERIFY`，`IAS`，`ZEFR`。<br><p><span style="color:darkred"><b>注意</b></span>：出价后第三方品牌安全监测目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。|
##|viewability_vast_url |string|出价后第三方监测合作伙伴用于监测可见性的封装的 VAST 网址。当`brand_safety_postbid_partner`非`IAS`时本字段为空值。<br><p><span style="color:darkred"><b>注意</b></span>：出价后第三方品牌安全监测目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。|
##|brand_safety_postbid_partner |string| 出价后第三方品牌安全监测合作伙伴。枚举值： `UNSET`，`DOUBLE_VERIFY`，`IAS`，`ZEFR`。<br><p><span style="color:darkred"><b>注意</b></span>：出价后第三方品牌安全监测目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。 |
##|brand_safety_vast_url| string|出价后第三方监测合作伙伴用于监测品牌安全的封装的 VAST 网址。当`brand_safety_postbid_partner`非`IAS`时本字段为空值。<br><p><span style="color:darkred"><b>注意</b></span>：出价后第三方品牌安全监测目前为白名单功能。如需使用此功能，请联系您的TikTok销售代表。|
##|impression_tracking_url |string|默认展示监测 URL。  |
##|click_tracking_url |string|点击监测 URL。|
##|playable_url |string| 试玩广告 URL。|
##|operation_status|string|广告的操作状态。<ul><li>`ENABLE`：广告处于启用（“开”）状态。</li><li>`DISABLE`：广告处于未启用（“关”）状态。</li><li>`FROZEN`：广告处于冻结状态，无法再次启用。</li></ul>  |
##|secondary_status|string| 广告状态（二级状态）。枚举值详见[枚举值-二级状态-广告状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。<br><p><span style="color:darkred"><b>注意</b></span>：沙箱环境下本字段不返回，因为广告未实际投放。 |
##|creative_type|string| 直播购物广告、商品购物广告或应用预注册场景中的创意素材类型。枚举值：<ul><li>`SHOP_PDP`：短视频带货广告，包含一个商品链接。</li><li>`SHOP_PLP`: 短视频带货广告，包含6-50个商品链接。</li><li> `SHORT_VIDEO_LIVE`: 短视频引流至直播间广告。</li><li> `DIRECT_LIVE`: 直播间带货。每个推广系列只能有一个直播间。</li><li>`PSA`：商品视觉元素将作为广告创意使用。 </li><li>`CUSTOM_INSTANT_PAGE`：自定义 TikTok 即时体验页面。<br>仅当推广系列层级 `app_promotion_type`设置为`APP_PREREGISTRATION`，且广告组层级`promotion_website_type`设置为`TIKTOK_NATIVE_PAGE`时返回此值。</li></ul>|
##|app_name |string|应用名称。|
##|display_name |string|落地页或纯曝光广告的显示名称。|
##|avatar_icon_web_uri|string|广告头像图片 ID。|
##|profile_image_url |string|头像 URL。|
##|creative_authorized |boolean| 是否允许在我们的 TikTok For Business 创意中心展示您的广告。仅对非美国广告主有效。默认值：`false`。<br><p><span style="color:darkred"><b>注意</b></span>：`creative_authorized`仅可用于视频广告。|
##|is_aco |boolean| 是否为程序化广告或智能创意广告。若为程序化广告或智能创意广告，则为`true`。|
##|is_new_structure|boolean|该广告是否为新结构（广告与对应推广系列及广告组结构相同）。|
##|optimization_event|string|广告组转化事件。参阅[转化事件](https://ads.tiktok.com/marketing_api/docs?id=1739361474981889)，获取详细信息。 |
#|page_info |object | 分页信息。 |
##|page |number | 当前页数。 |
##|page_size |number | 分页大小。 |
##|total_number |number | 总结果数。 |
##|total_page |number | 总页数。 |
|request_id |string|请求的日志ID，唯一标识一个请求。  |

示例

获取升级版 Smart+ 推广系列中的广告（素材组）层级数据

(code Success-Response http)
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [
            {
                "campaign_id": "{{campaign_id}}",
                "adgroup_id": "{{adgroup_id}}",
                "campaign_name": "{{campaign_name}}",
                //ad name
                "ad_name": "{{ad_name}}",
                //ad ID
                "ad_id_v2": "{{ad_id_v2}}",
                "advertiser_id": "{{advertiser_id}}",
                "campaign_automation_type": "UPGRADED_SMART_PLUS",
                "adgroup_name": "{{adgroup_name}}"
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 10,
            "total_page": 1,
            "total_number": 1
        }
    }
}
(/code)

获取升级版 Smart+ 推广系列中的素材层级数据

(code Success-Response http)
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "list": [
            {
                "video_id": "{{video_id}}",
                "advertiser_id": "{{advertiser_id}}",
                "campaign_name": "{{campaign_name}}",
                "adgroup_name": "{{adgroup_name}}",
                "campaign_id": "{{campaign_id}}",
                "adgroup_id": "{{adgroup_id}}",
                "modify_time": "{{modify_time}}",
                "identity_id": "{{identity_id}}",
                //creative ID
                "ad_id": "{{ad_id}}",
                "secondary_status": "AD_STATUS_CAMPAIGN_DISABLE",
                "identity_type": "CUSTOMIZED_USER",
                "campaign_automation_type": "UPGRADED_SMART_PLUS_CREATIVE",
                "ad_text": "",
                //ad ID
                "smart_plus_ad_id": "{{smart_plus_ad_id}}",
                "operation_status": "ENABLE",
                //creative name
                "ad_name": "{{ad_name}}",
                "create_time": "{{create_time}}",
                "image_ids": [
                    "{{image_id}}"
                ]
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 10,
            "total_page": 1,
            "total_number": 1
        }
    }
}
(/code)
← 创建广告更新广告 →

内容来源：TikTok API for Business 官方文档 · 本地归档

在接这个接口时卡住了？
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →