← 返回目录
📁 API Reference › Upgraded Smart+ › Ads

预览升级版 Smart+ 广告

你可以使用本接口预览要创建的或已有的升级版 Smart+ 广告。

请求

地址 https://business-api.tiktok.com/open_api/v1.3/smart_plus/ad/preview/

方法 POST

Header

|字段{35%}|类型{15%}|描述{50%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://business-api.tiktok.com/portal/docs/marketing-api-authentication/v1.3)接口获取。|
|Content-Type {必填}|string|请求信息类型。<br>允许值：`application/json`。|

参数

预览要创建的广告

这让你能够在创建广告前进行预览。

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_id {必填}|string|广告主 ID。|
|preview_type {必填}|string|预览类型。<br><br>枚举值： <ul><li>`ADS_CREATION`：按广告创建参数预览广告。</li></ul>|
|catalog_enabled|boolean|是否在推广系列中使用商品库。<br><br>支持的值：`true`、`false`。|
|catalog_id {+条件必填}|string|当 `catalog_enabled` 为 `true` 时，此为必填字段。<br><br>用于广告组的商品库的 ID。<br><br>若想获取你的商务中心内的商品库，需使用 [/catalog/get/](1740315452868610.html) 接口。|
|catalog_authorized_bc_id {+条件必填}|string|当 `catalog_enabled` 为 `true` 时，此为必填字段。<br><br>商品库 (`catalog_id`) 所属的商务中心的 ID。|
|creative_list {必填}|object[]|创意列表。<br><br>数量范围：1-31。|
#|creative_info {必填}|object|创意信息。|
##|video_info {+条件必填}|object|使用以下广告类型时，此为必填字段：<ul><li>非 Spark Ads 单视频广告。 </li><li>通过 Spark Ads 推送创建的 Spark Ads 单视频广告。</li></ul><br>视频信息。|
###|video_id {+条件必填}|string|当已指定 `video_info` 时，此为必填字段。<br><br>视频 ID。<br><br>若想上传视频并获取视频 ID，需使用 [/file/video/ad/upload/](1737587322856449.html) 接口。<br>若想搜索广告账号内的视频，需使用 [/file/video/ad/search/](1740050472224769.html) 接口。|
##|image_info {+条件必填}|object[]|<ul><li>使用以下广告类型时，此为必填字段：<ul><li>非 Spark Ads 单视频广告。需传入视频封面。</li><li>通过 Spark Ads 推送创建的 Spark Ads 单视频广告。需传入视频封面。</li><li>非 Spark Ads 标准轮播广告。需传入 1-35 张轮播图片。</li><li>通过 Spark Ads 推送创建的 Spark Ads 标准轮播广告。需传入 1-35 张轮播图片。</li></ul></li><li>不支持商品库轮播广告。</li></ul><br>图片信息。|
###|web_uri {+条件必填}|string|当已指定 `image_info` 时，此为必填字段。<br><br>图片 ID。<br><br>若想上传图片并获取图片 ID，需使用 [/file/image/ad/upload/](1739067433456642.html) 接口。<br>若想搜索广告账号内的图片，需使用 [/file/image/ad/search/](1740052016789506.html) 接口。|
##|music_info {+条件必填}|object|<ul><li>如果属于以下场景，此为必填字段：<ul><li>创建标准轮播广告时，包括：<ul><li>非 Spark Ads 标准轮播广告</li><li>通过 Spark Ads 推送创建的 Spark Ads 标准轮播广告</li><li>通过 Spark Ads 提取创建的 Spark Ads 标准轮播广告</li></ul></li><li>当 `objective_type` 为 `WEB_CONVERSIONS` 并且 `catalog_creative_toggle` 为 `true` 时。系统将自动生成商品库轮播广告。</li></ul></li></ul>音乐信息。|
###|music_id {+条件必填}|string|当已指定 `music_info` 时，此为必填字段。<br><br>轮播广告中使用的音乐的 ID。|
##|tiktok_item_id {+条件必填}|string|<ul><li>通过 Spark Ads 提取创建 Spark Ads 时，此为必填字段，包括：<ul><li>通过 Spark Ads 提取创建的 Spark Ads 单视频广告。需传入 TikTok 视频帖子。</li><li>通过 Spark Ads 提取创建的 Spark Ads 标准轮播广告。需传入 TikTok 照片帖子。</li></ul></li><li>当 `catalog_creative_toggle` 为 `true` 时，不支持此字段。</li></ul><br>作为广告 (Spark Ads) 投放的 TikTok 帖子的 ID。<br><br>传入从 [/tt_video/info/](1738376324021250.html) 和 [/identity/video/get/](1740218475032577.html) 接口的返回结果中获取的 `item_id`。<br><br>在传入 `tiktok_item_id` 时，无需传入对象 `image_info`、`video_info` 和 `title_list`。<br><br><p><span style="color:darkred"><b>注意</b></span>：使用 Spark Ads，即表示你确认拥有将视频中的音乐用于商业用途的权利。|
##|identity_type {+条件必填}|string|当不使用商品库创意创建 Spark Ads 时必填。<br><br>广告发布身份类型。<br><br>枚举值：`AUTH_CODE`、`TT_USER`、`BC_AUTH_TT`。<br><br>查看[广告发布身份](1738958351620097.html)文档，详细了解广告发布身份。<br><br><p><span style="color:darkred"><b>注意</b></span>： <ul><li>若想使用电商商品库中的创意创建 Spark Ads，需在 `ad_configuration` 中传入 `identity_type` 和 `identity_id`。</li><li>如果此字段设置为 `TT_USER`、`BC_AUTH_TT` 或 `AUTH_CODE`，且满足以下两个条件，那么需要通过 `call_to_action_id` 传入动态 CTA。<ul><li>推广系列层级的 `objective_type` 为 `APP_PROMOTION` 或 `WEB_CONVERSIONS`。</li><li>广告组层级的 `placement_type` 为 `PLACEMENT_TYPE_NORMAL` 且 `placements` 包含 `PLACEMENT_TIKTOK`，或 `placement_type` 为 `PLACEMENT_TYPE_AUTOMATIC`。</li></ul></li></ul>|
##|identity_id {+条件必填}|string|当不使用商品库创意创建 Spark Ads 时必填。<br><br>广告发布身份 ID。<br><br><p><span style="color:darkred"><b>注意</b></span>：若想使用电商商品库中的创意创建 Spark Ads，需在 `ad_configuration` 中传入 `identity_type` 和 `identity_id`。</p>|
##|identity_authorized_bc_id {+条件必填}|string|当 `creative_info` 中的 `identity_type` 为 `BC_AUTH_TT` 时必填。<br><br>与“添加到商务中心的 TikTok 用户”类型广告发布身份关联的商务中心 ID。|
|ad_text_list {+条件必填}|object[]|当未指定 `tiktok_item_id` 时，此为必填字段。<br><br>广告文案列表。<br>广告文案作为广告创意的一部分展示给受众，用于传递你希望传达的信息。<br><br>最大数量：5。|
#|ad_text {+条件必填}|string|当已指定 `ad_text_list` 时，此为必填字段。<br><br>广告文案。|
|call_to_action_list|object[]|行动引导文案列表。<br><br>最大数量：3。<br><br><p><span style="color:darkred"><b>注意</b></span>：<ul><li>此字段不支持升级版 Smart+ 线索收集推广系列。</li><li>预览链接将仅显示此列表中的第一个行动引导文案。</li><li>不能同时设置`call_to_action_list` 和 `call_to_action_id` 。</li></ul>|
#|call_to_action {+条件必填}|string|当传入 `call_to_action_list` 时，此为必填字段。<br><br>行动引导文案。<br><br>枚举值参见[枚举值 - 行动引导文案](https://business-api.tiktok.com/portal/docs?id=1737174886619138#item-link-Call-to-action)。|
|ad_configuration|object|其他配置。|
#|identity_type {+条件必填}|string|在以下任意场景中，此为必填字段：<ul><li>创建投放到非 TikTok 广告位的非 Spark Ads。现已不再支持将非 Spark Ads 投放到 TikTok 广告位。</li><li>使用电商商品库中的创意创建 Spark Ads。如需详细了解如何创建此类广告，参见[创建升级版 Smart+ 电商商品库广告](1847302895272962.html)。</li></ul><br>广告发布身份类型。<ul><li>对于投放到非 TikTok 广告位的非 Spark Ads，广告发布身份类型的枚举值为：`CUSTOMIZED_USER`。</li><li>对于升级版 Smart+ 电商商品库 Spark Ads（`catalog_creative_toggle` 为 `true`），广告发布身份类型的枚举值为：`TT_USER`、`BC_AUTH_TT`。</li></ul><br>查看[广告发布身份](1738958351620097.html)文档，详细了解广告发布身份。|
#|identity_id {+条件必填}|string|在以下任意场景中，此为必填字段：<ul><li>创建投放到非 TikTok 广告位的非 Spark Ads。现已不再支持将非 Spark Ads 投放到 TikTok 广告位。</li><li>使用电商商品库中的创意创建 Spark Ads。如需详细了解如何创建此类广告，参见[创建升级版 Smart+ 电商商品库广告](1847302895272962.html)。</li></ul><br>广告发布身份 ID。|
#|identity_authorized_bc_id {+条件必填}|string|当 `ad_configuration` 中的 `identity_type` 为 `BC_AUTH_TT` 时必填。<br><br>与“添加到商务中心的 TikTok 用户”类型广告发布身份关联的商务中心 ID。|
#|product_specific_type {+条件必填}|string|当推广系列层级的 `catalog_enabled` 为 `true` 时，此为必填字段。<br><br><br>选择商品的不同维度。<br><br>枚举值：<ul><li>`ALL`：允许 TikTok 动态选择所有商品。</li><li>`PRODUCT_SET`：传入商品系列。TikTok 将动态选择该商品系列中的商品。</li><li>`CUSTOMIZED_PRODUCTS`：传入自定义数量的商品。</li></ul><br><ul><li> 如果此字段设置为 `ALL`，无需输入 `product_set_id` 和 `product_ids`。</li><li> 如果此字段设置为 `PRODUCT_SET`，需传入 `product_set_id`。</li><li> 如果此字段设置为 `CUSTOMIZED_PRODUCTS`，`product_ids` 为必填字段。</li></ul>|
#|product_set_id {+条件必填}|string|当 `product_specific_type` 为 `PRODUCT_SET` 时，此为必填字段。<br><br>商品系列 ID。<br><br><ul><li>若想获取广告账号内的商品系列，需使用 [/catalog/set/get/](1740570556295169.html) 接口。</li><li> 若想创建商品系列，需使用 [/catalog/set/create/](1740572891104257.html) 接口。</li></ul>|
#|product_ids {+条件必填}|string[]|当 `product_specific_type` 为 `CUSTOMIZED_PRODUCTS` 时，此为必填字段。<br><br>商品库商品的 ID。<br><br>最大数量：20。<br><br>若想获取每个商品库商品的 ID (`product_id`)，需使用 [/catalog/product/get/](1740564136678402.html) 接口。|
#|catalog_creative_toggle|boolean|仅当 `catalog_enabled` 为 `true` 时生效。<br><br>是否启用从商品库自动选择创意。<br><br>支持的值：`true`、`false`。<br>默认值：`false`。<br><br>如果将此字段设置为 `true`，需提供仅包含 `music_info` 的 `creative_info`，以指定商品库轮播中使用的音乐。|
#|catalog_creative_info|object|仅当满足以下条件时生效：<ul><li>广告为[升级版 Smart+ 电商商品库广告](1847302895272962.html)或[升级版 Smart+ 流媒体广告](https://business-api.tiktok.com/portal/docs/create-upgraded-smart-streaming-ads/v1.3)。</li><li>`catalog_creative_toggle` 为 `true`。</li></ul><br>在广告中使用的商品库创意的其他设置。|
##|catalog_media_settings|string[]|在广告中使用的电商商品库或娱乐商品库创意的类型。<br><br>对于[升级版 Smart+ 电商商品库广告](1847302895272962.html)，枚举值为：<ul><li>`VIDEO`：视频。</li><li>`IMAGE`：图片。</li><li>`TEMPLATE_VIDEO`：视频模板。如果在 `catalog_media_settings` 中包含该值，可选择同时传入 `catalog_template_video_id`。<ul><li>如果不传入 `catalog_template_video_id`，你的商品库中的所有视频模板和视频 URL 将用于生成广告。</li><li>如果传入 `catalog_template_video_id`，所选视频模板将用于生成广告。</li></ul></li></ul><br>对于[升级版 Smart+ 流媒体广告](https://business-api.tiktok.com/portal/docs/create-upgraded-smart-streaming-ads/v1.3)，枚举值为：<ul><li>`VIDEO`：视频。</li><li>`TEMPLATE_VIDEO`：视频模板。如果在 `catalog_media_settings` 中包含该值，不可同时传入 `catalog_template_video_id`。<ul><li>你的商品库中的所有视频模板和视频 URL 将用于生成广告。</li></ul></li><li>`MULTI_SHOW`：多影片。多影片体验是一种支持自动播放的视频轮播体验，旨在引导用户探索内容库中契合其兴趣的丰富资源，并与之互动。多影片体验由来自商品库的 4 个视频磁贴组成。每个磁贴片段从左上角开始按顺序播放，你可以为磁贴设置相应的特定影片落地页。</li></ul>|
##|catalog_template_video_id|string|仅当满足以下条件时生效：<ul><li>广告为[升级版 Smart+ 流媒体广告](https://business-api.tiktok.com/portal/docs/create-upgraded-smart-streaming-ads/v1.3)。</li><li> `catalog_media_settings` 中包含 `TEMPLATE_VIDEO`。</li></ul><br>在广告中使用的商品库视频模板的 ID。<br><br>若想获取你的商品库中的视频模板（视频包）ID，需使用 [/catalog/video_package/get/](1740574099715073.html) 接口。<br>如需了解如何在 TikTok 广告管理平台上创建视频包，参见[如何在商品库中创建视频包](https://ads.tiktok.com/help/article/how-to-create-video-packages-in-a-catalog)。|
#|call_to_action_id|string|要在广告中使用的行动引导文案 (CTA) 组合（也称为动态 CTA）的 ID。CTA 素材包是一组自动优化的 CTA。<br><br>如需详细了解自动优化的 CTA，参见[智能推荐行动引导文案 > 动态优选行动引导文案](https://business-api.tiktok.com/portal/docs?id=1740307296329730#item-link-Dynamic%20CTAs%20)。<br><br><p><span style="color:darkred"><b>注意</b></span>：不能同时设置 `call_to_action_list` 和 `call_to_action_id`。|

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/smart_plus/ad/preview/' \
--header 'Access-Token: "{{Access-Token}}"' \
--header 'Content-Type: application/json' \
--data '{
    "advertiser_id": "{{advertiser_id}}",
    "preview_type": "ADS_CREATION",
    "catalog_enabled": true,
    "catalog_id": "{{catalog_id}}",
    "catalog_authorized_bc_id": "{{catalog_authorized_bc_id}}",
    "creative_list": [
        {
            "creative_info": {
                "video_info": {
                    "video_id": "{{video_id}}"
                }
            },
            "image_info": [
                {
                    "web_uri": "{{web_uri}}"
                }
            ]
        },
        {
            "creative_info": {
                "tiktok_item_id": "{{tiktok_item_id}}",
                "identity_id": "{{identity_id}}",
                "identity_type": "BC_AUTH_TT",
                "identity_bc_id": "{{identity_bc_id}}"
            }
        },
        {
            "creative_info": {
                "image_info": [
                    {
                        "web_uri": "{{web_uri}}"
                    },
                    {
                        "web_uri": "{{web_uri}}"
                    }
                ],
                "music_info": {
                    "music_id": "{{music_id}}"
                }
            }
        },
        {
            "creative_info": {
                "music_info": {
                    "music_id": "{{music_id}}"
                }
            }
        }
    ],
    "ad_text_list": [
        {
            "ad_text": "{{ad_text}}"
        },
        {
            "ad_text": "{{ad_text}}"
        }
    ],
    "call_to_action_list": [
        {
            "call_to_action": "APPLY_NOW"
        },
        {
            "call_to_action": "DOWNLOAD_NOW"
        }
    ],
    "ad_configuration": {
        "product_specific_type": "ALL",
        "catalog_creative_toggle": true
    }
}'
(/code)

预览已有广告

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_id {必填}|string|广告主 ID。|
|preview_type {必填}|string|预览类型。<br><br>枚举值：<ul><li>`AD`：预览已有广告。</li></ul>|
|smart_plus_ad_id {必填}|string|要预览的升级版 Smart+ 广告的 ID。<br><br>若想获取升级版 Smart+ 广告的 ID 列表，需使用 [/smart_plus/ad/get/](1843317378982914.html) 接口。|

示例

(code curl http)
curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.3/smart_plus/ad/preview/' \
--header 'Access-Token: "{{Access-Token}}"' \
--header 'Content-Type: application/json' \
--data '{
    "advertiser_id": "{{advertiser_id}}",
    "preview_type": "AD",
    "smart_plus_ad_id": "{{smart_plus_ad_id}}"
}'
(/code)

返回

|字段{30%}|类型{15%}|描述{55%}|
|-|-|-|
|code |number|返回码。完整返回码列表及描述参见[附录 - 返回码](https://business-api.tiktok.com/portal/docs/return-codes-appendix/v1.3)。|
|message |string|返回信息。更多信息参见[附录 - 返回码](https://business-api.tiktok.com/portal/docs/return-codes-appendix/v1.3)。|
|request_id|string| 请求的日志 ID，唯一标识一个请求。|
|data|object|返回数据。|
#|preview_link|string|预览链接。<br><br>有效期：30 天。|
#|iframe|string|包含预览链接的 iframe 代码片段。可将 iframe 代码嵌入 HTML 文件中。|

示例

(code curl http)
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "iframe": "<iframe src=\"https://ads.tiktok.com/ad_preview_tool?ad_preview_id={{ad_preview_id}}\"></iframe>",
        "preview_link": "{{preview_link}}"
    }
}
(/code)
← 广告更新升级版 Smart+ 广告的操作状态 →

内容来源：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 每日平台更新简报 →