creative_ads_preview_create

Ad format. Use `SINGLE_VIDEO` for single video ads, `SINGLE_IMAGE` for single image ads (supported only on Pangle), `CAROUSEL_ADS` for TikTok Standard Carousel ads, `CATALOG_CAROUSEL` for TikTok Catalog Carousel ads, and `LIVE_CONTENT` for Live Shopping Ads. `CAROUSEL_ADS` requires `objective_type` to be `REACH`, `WEB_CONVERSIONS`, `APP_PROMOTION`, `LEAD_GENERATION`, or `TRAFFIC`.

Required when `preview_type=AD`. ID of the existing ad to preview.

Ad text shown in the creative. For ad-creation previews, this field is required for non-Spark Ads. Length must be 1-100 characters and cannot contain emoji. Each Chinese or Japanese word counts as two characters; each English letter counts as one.

Advertiser ID. For ad and ad-creation previews, you must have Operator or Admin permission for the ad account; check /bc/asset/get/ and ensure the returned `advertiser_role` is `ADMIN` or `OPERATOR`. If the ad uses a catalog, you also need catalog permission, and /bc/asset/get/ should return `catalog_role` as `ADMIN` or `AD_PROMOTE`.

Valid only when `objective_type=LEAD_GENERATION`, `catalog_enabled=true`, `catalog_id` points to an Auto-Model catalog, and `ad_format=CATALOG_CAROUSEL`. Types of disclaimers shown in Automotive Carousel Ads for Models. Max size: 1.

Call-to-action text. For TikTok ads, either this field or `call_to_action_id` must be specified; if both are passed, this field is ignored. For live shopping ads, the CTA must be `WATCH_LIVE`. If `objective_type` is `REACH` or `VIDEO_VIEW` and `landing_page_url` or `page_id` is set, either `call_to_action` or `call_to_action_id` is required. If `objective_type` is `APP_PROMOTION`, `WEB_CONVERSIONS`, or `TRAFFIC`, either `call_to_action` or `call_to_action_id` is required. If `objective_type` is `LEAD_GENERATION`: when `promotion_type` is `LEAD_GENERATION`, either `call_to_action` or `call_to_action_id` is required; when `promotion_type` is `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`, this field is required and must be `SEND_MESSAGE`; when `promotion_type` is `LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`, this field is required and cannot be `CALL_NOW`; when `promotion_type` is `LEAD_GEN_CLICK_TO_CALL`, this field is required. If `objective_type` is `PRODUCT_SALES`, this field is required.

CTA portfolio ID for auto-optimized CTAs. If both this field and `call_to_action` are specified, `call_to_action` is ignored. If `objective_type` is `REACH` or `VIDEO_VIEW` and `landing_page_url` or `page_id` is set, either `call_to_action` or `call_to_action_id` is required. If `objective_type` is `APP_PROMOTION`, `WEB_CONVERSIONS`, or `TRAFFIC`, either `call_to_action` or `call_to_action_id` is required. If `ad_format` is `CAROUSEL_ADS` or `CATALOG_CAROUSEL`, this field is not supported. If `objective_type` is `LEAD_GENERATION`, then when `promotion_type` is `LEAD_GENERATION`, either `call_to_action` or `call_to_action_id` is required; when `promotion_type` is `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`, `LEAD_GEN_CLICK_TO_SOCIAL_MEDIA_APP_MESSAGE`, or `LEAD_GEN_CLICK_TO_CALL`, this field is not supported.

Creative portfolio ID. For `preview_type=CARD`, use the ID of an existing Display Card, Countdown Sticker, or Gift Code Sticker portfolio. In ad-creation previews, this field can also be used with supported portfolio types including Display Card, Website info card, Product Card, Product Tiles, Countdown Sticker, Gift Code Sticker, Gesture, and Superlike. Supported ad-creation scenarios include: `objective_type=REACH`, `promotion_type=WEBSITE`, `placements=PLACEMENT_TIKTOK`, `ad_format=SINGLE_VIDEO`; `TRAFFIC` + `WEBSITE` + `PLACEMENT_TIKTOK` + `SINGLE_VIDEO`; `VIDEO_VIEWS` + `PLACEMENT_TIKTOK` + `SINGLE_VIDEO`; `ENGAGEMENT` where only Countdown Sticker is allowed; `APP_PROMOTION` + `WEBSITE` + `PLACEMENT_TIKTOK` + `SINGLE_VIDEO`; `LEAD_GENERATION` where only Display Card is allowed; `WEB_CONVERSIONS` + `PLACEMENT_TIKTOK` + `SINGLE_VIDEO`; and `PRODUCT_SALES` + `PLACEMENT_TIKTOK` + `SINGLE_VIDEO`.

Valid only when `ad_format` is `CATALOG_CAROUSEL` and additional images have been configured for the specified products. Selects which additional product image index to use in the VSA Carousel ad. If omitted, the main catalog product images are used. Range: 0-9. The index maps to the position within each product's `additional_image_urls`; if the index exceeds the number of additional image URLs for a product, the field is ignored and the product's main `image_url` is used.

Same as `bc_id`. Use this field when previewing catalog items.

Product catalog ID supplying the products whose links are shown in the ad. Required when `ad_format` is `CATALOG_CAROUSEL`. You must have Ad promotion or Catalog management permission for the catalog; verify via /bc/asset/get/ and ensure the returned `catalog_role` is `ADMIN` or `AD_PROMOTE`.

IDs of destinations. Max size:20.

Brand name shown in video or image previews. Allowed length: 1-40 English characters, or 1-20 Chinese/Japanese/Korean characters.

Dynamic destination strategy. Not supported when `ad_format` is `CAROUSEL_ADS` or `CATALOG_CAROUSEL`. `DLP` enables Dynamic Landing Page behavior; `UNSET` leaves it unset.

Dynamic format. Not supported when `ad_format` is `CAROUSEL_ADS` or `CATALOG_CAROUSEL`. `UNSET` leaves it unset; `DYNAMIC_CREATIVE` enables smart creative to show different videos, product cards, and destinations based on purchase intent.

Required when all of the following are true: `objective_type=LEAD_GENERATION`, `catalog_enabled=true`, `catalog_id` refers to an Auto-Model catalog, and `ad_format=CATALOG_CAROUSEL`. CTA for the end card (`image_ids`) of an Automotive Carousel Ad for Models.

IDs of flights.

IDs of hotels

Required when `identity_type` is `BC_AUTH_TT`. Business Center ID associated with the TikTok Account User in Business Center identity.

Identity ID. If you are not using Spark Ads, use `identity_id` together with `identity_type=CUSTOMIZED_USER` for ad management.

Identity type. `CUSTOMIZED_USER` is for custom identity; `AUTH_CODE`, `TT_USER`, and `BC_AUTH_TT` are for Spark Ads. When `ad_format` is `CATALOG_CAROUSEL`, this field can only be `CUSTOMIZED_USER`. If `objective_type` is `LEAD_GENERATION` and `promotion_type` is `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`, Spark Ads must be used and `identity_type` must be `TT_USER` or `BC_AUTH_TT`. If `objective_type` is `LEAD_GENERATION` and `promotion_type` is not `LEAD_GEN_CLICK_TO_TT_DIRECT_MESSAGE`, both Spark and non-Spark ads are supported, so any enum value is allowed. If `objective_type` is `ENGAGEMENT`, only Spark Ads are supported and `identity_type` must be `AUTH_CODE`, `TT_USER`, or `BC_AUTH_TT`. When `identity_type` is `BC_AUTH_TT`, `identity_authorized_bc_id` is required.

Required when `preview_type=SINGLE_IMAGE`. Image ID used for image previews. Different placements have different creative specifications.

List of image IDs used in an ad or as a video cover. Required when `ad_format` is `SINGLE_IMAGE`; when `ad_format` is `CAROUSEL_ADS` and you are creating Standard Carousel Spark Ads via Spark Ads Push or Standard Carousel non-Spark Ads; and when `ad_format` is `CATALOG_CAROUSEL`, `catalog_enabled=true`, and `catalog_id` points to an Auto-Model catalog. When `ad_format=CAROUSEL_ADS`, size must be 1-35 and image order controls carousel order. When `ad_format=CATALOG_CAROUSEL` with `catalog_enabled=true`, only one image is allowed and it is used as the summary photo for Automotive Ads for Models. When `ad_format=SINGLE_IMAGE`, only one image ID is allowed.

Whether to use TikTok Instant Product Page. Not supported when `ad_format` is `CAROUSEL_ADS` or `CATALOG_CAROUSEL`. When `dynamic_destination=DLP`, you do not need this field. When `dynamic_destination=UNSET`, you can set this field to `true` to use TikTok Instant Product Page and then you do not need to pass `page_id`.

Product SPU IDs. If `catalog_id` is specified and `product_specific_type=PRODUCT_SET`, pass either `item_group_ids` or `product_set_id`. This field is also required when `shopping_ads_type=VIDEO` and `product_source=STORE`, and when `shopping_ads_type=PRODUCT_SHOPPING_ADS`, `product_source=STORE`, and `product_specific_type=CUSTOMIZED_PRODUCTS`.

Landing page URL. If `objective_type` is `APP_PROMOTION`, `WEB_CONVERSIONS`, or `TRAFFIC` and `promotion_type` is `WEBSITE`, either `page_id` or `landing_page_url` is required. If `objective_type` is `APP_PROMOTION` or `TRAFFIC` and `promotion_type` is `APP_ANDROID` or `APP_IOS`, neither `page_id` nor `landing_page_url` can be used. If `shopping_ads_fallback_type` is `CUSTOM`, you must also pass `landing_page_url`.

Required when `ad_format` is `CAROUSEL_ADS` and you create Standard Carousel Spark Ads via Spark Ads Push or Standard Carousel non-Spark Ads, or when `ad_format` is `CATALOG_CAROUSEL`. ID of the music used in the TikTok Carousel Ad.

Instant page ID. For `preview_type=PAGE`, use this field to preview an existing instant page. In ad-creation previews, this field is used to preview a TikTok Instant Page. If `objective_type` is `APP_PROMOTION`, `WEB_CONVERSIONS`, or `TRAFFIC` and `promotion_type` is `WEBSITE`, either `page_id` or `landing_page_url` is required. If `objective_type` is `APP_PROMOTION` or `TRAFFIC` and `promotion_type` is `APP_ANDROID` or `APP_IOS`, neither `page_id` nor `landing_page_url` can be used. If `ad_format` is `CATALOG_CAROUSEL`, this field is not supported. When `dynamic_destination=UNSET`, setting `instant_product_page_used=true` means you do not need to pass `page_id`.

The app where the ad is delivered. For ad-creation previews, when `ad_format` is `CAROUSEL_ADS` or `CATALOG_CAROUSEL`, set this field to `PLACEMENT_TIKTOK` or omit it. Supported values vary by `objective_type`: `PLACEMENT_TIKTOK` is supported for `REACH`, `TRAFFIC`, `VIDEO_VIEWS`, `ENGAGEMENT`, `APP_PROMOTION`, `LEAD_GENERATION`, `WEB_CONVERSIONS`, and `PRODUCT_SALES`; `PLACEMENT_PANGLE` is supported only for `TRAFFIC`, `APP_PROMOTION`, `WEB_CONVERSIONS`, or `LEAD_GENERATION` when `promotion_type` is `LEAD_GENERATION`; `PLACEMENT_GLOBAL_APP_BUNDLE` is supported only when `objective_type` is `REACH`; `ALL` is supported only for `TRAFFIC`, `APP_PROMOTION`, `WEB_CONVERSIONS`, or `LEAD_GENERATION` when `promotion_type` is `LEAD_GENERATION`. For existing-ad previews, pass this field only if you want a non-TikTok placement; otherwise it defaults to `PLACEMENT_TIKTOK`.

Preview format, whose valid values depend on `placement` and `tiktok_subplacement`. Default: `IN_FEED`. When `placement` is `PLACEMENT_TIKTOK`, allowed values are `IN_FEED`, `SEARCH_RESULTS`, `SEARCH_FEED`, `TIKTOK_LITE`, `PRODUCT_SEARCH`, and `PRODUCT_SHOP_CENTER`. When `placement` is `PLACEMENT_TIKTOK` and `tiktok_subplacement` is `LEMON8`, allowed values are `IN_FEED` and `IN_FEED_TWO_COLUMNS`. When `placement` is `PLACEMENT_GLOBAL_APP_BUNDLE`, allowed values are `APP_OPEN`, `IN_FEED`, and `IN_FEED_TWO_COLUMNS`. `SEARCH_FEED` and `TIKTOK_LITE` are valid only when `objective_type` is `REACH`, `VIDEO_VIEWS`, or `ENGAGEMENT` and `placement` is `PLACEMENT_TIKTOK`. `PRODUCT_SEARCH` and `PRODUCT_SHOP_CENTER` are available only for Video Shopping Ads and Product Shopping Ads. This field is not supported when `placement` is `PLACEMENT_PANGLE`.

Selects what to preview. Use `ADS_CREATION` to preview ads from creation parameters, `AD` to preview an existing ad, `CARD` to preview an existing interactive add-on, `PAGE` to preview an existing instant page, `SINGLE_VIDEO` to preview a video ad from parameters, and `SINGLE_IMAGE` to preview an image ad from parameters.

Product set ID. If `catalog_id` is specified and `product_specific_type=PRODUCT_SET`, pass either `item_group_ids` or `product_set_id`.

Required only for Video Shopping Ads and Product Shopping Ads. Product source for promoted products. For `shopping_ads_type=VIDEO`, you can use `STORE` or `SHOWCASE`. For `shopping_ads_type=PRODUCT_SHOPPING_ADS`, set this field to `STORE`.

How to choose products. Required when `ad_format` is `CATALOG_CAROUSEL`; the product scope must contain at least two products. `ALL` lets TikTok choose from all catalog products and does not require `sku_ids`, `item_group_ids`, or `product_set_id`. `PRODUCT_SET` requires either `item_group_ids` or `product_set_id`. `CUSTOMIZED_PRODUCTS` requires `sku_ids` or `vehicle_ids`. When `shopping_ads_type` is `PRODUCT_SHOPPING_ADS` and `product_source` is `STORE`, allowed values are `ALL` or `CUSTOMIZED_PRODUCTS`; with `ALL`, no product ID fields are needed, and with `CUSTOMIZED_PRODUCTS`, `item_group_ids` is required. When `shopping_ads_type` is `VIDEO` and `product_source` is `STORE`, specify products through `item_group_ids`. When `shopping_ads_type` is `VIDEO` and `product_source` is `SHOWCASE`, specify products through `showcase_products`. When `shopping_ads_type` is `LIVE`, you do not need to specify products.

Profile image ID used in video previews.

Required when `objective_type` is `PRODUCT_SALES` and `catalog_id` is not specified. Shopping ads type: `VIDEO` for Video Shopping Ads, `LIVE` for Live Shopping Ads, `PRODUCT_SHOPPING_ADS` for Product Shopping Ads. When `ad_format` is `CATALOG_CAROUSEL`, set this field to `VIDEO` or omit it.

Required when `shopping_ads_type` is `VIDEO` and `product_source` is `SHOWCASE`. List of Showcase products to use in the ad. Max size: 20.

SKU IDs. Required when `catalog_id` points to an E-commerce catalog and `product_specific_type=CUSTOMIZED_PRODUCTS`. Max size: 20.

Required when `store_id` is passed. Business Center ID authorized to access the TikTok Shop referenced by `store_id`.

TikTok Shop ID. Required when `shopping_ads_type` is `VIDEO` and `product_source` is `STORE`, or when `shopping_ads_type` is `PRODUCT_SHOPPING_ADS` and `product_source` is `STORE`. Optional when `shopping_ads_type` is `LIVE`. If you pass `store_id`, `store_authorized_bc_id` is required.

Thumbnail ID used in video previews.

Required when `identity_type` is `AUTH_CODE` or `BC_AUTH_TT` and you want to create Spark Ads through Spark Ads Pull. Not supported when `identity_type` is `CUSTOMIZED_USER`. This is the TikTok post ID used as the Spark Ad. Pass the `item_id` returned by /tt_video/info/ or /identity/video/get/. By using Spark Ads, you confirm that you have rights to use the music in the videos for commercial purposes.

Valid only when both `objective_type` is `REACH` and `placement` is `PLACEMENT_TIKTOK`. Selects TikTok subplacements. `LEMON8` enables Lemon8 surfaces; `UNSET` leaves it unset.

Vehicle IDs. Required when `catalog_id` points to an Auto-Model catalog and `product_specific_type=CUSTOMIZED_PRODUCTS`. Max size: 20.

Video strategy. Not supported when `ad_format` is `CAROUSEL_ADS` or `CATALOG_CAROUSEL`. `SINGLE_VIDEO` uses a video creative to promote products, `CATALOG_VIDEOS` generates a dynamic video from catalog information, `LIVE_STREAM` uses livestream and is supported only for Live Shopping Ads with ad format as Real-time LIVE, and `UNSET` leaves it unset. If `dynamic_format=DYNAMIC_CREATIVE`, this field must be `UNSET`.

Video ID. For ad-creation previews, this field is required when `ad_format` is `SINGLE_VIDEO` and is not supported when `ad_format` is `SINGLE_IMAGE`, `CAROUSEL_ADS`, or `CATALOG_CAROUSEL`. To create video Spark Ads using Spark Ads Push or create video non-Spark Ads, use `video_id`; for Spark Ads Pull, use `tiktok_item_id` instead. Different placements have different creative specifications.