获取 TTO 账号的 Spark Ads 视频推荐
此接口可用于获取与你的 TikTok One (TTO) Creator Marketplace 账号关联的最多 100 个视频帖子的 Spark Ads 推荐结果。
系统将视频与基准进行对比生成推荐结果，这些基准综合考虑受众互动、偏好、视频帖子属性（例如类型和时长）以及历史效果数据。根据这些因素，每个视频都会获得相应的推荐分数。视频分数越高，表明广告成功的可能性越大，推荐等级也更高。
此接口通过分析近一年关联你的 TTO Creator Marketplace 账号的视频帖子生成推荐。为确保得出有效的结果，建议为近一年至少关联 10 个视频帖子的 TTO Creator Marketplace 账号获取推荐。如果你的 TTO Creator Marketplace 账号在近一年关联超过 100 个视频帖子，返回结果将仅包含最适合作为 Spark Ads 投放的前 100 个视频，其余视频将被过滤。
我们的推荐模型会随着收集更多数据不断优化，力求为用户提供相关且富有吸引力的推荐内容。我们定期开展评估，确保模型预测结果与用户行为保持一致，并逐渐提升其有效性。
请求
地址 https://business-api.tiktok.com/open_api/v1.3/spark_ad/recommend/
方法 GET
Header
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|经 TTO Creator Marketplace 账号授权的访问令牌。<br><br>若想获取经 TTO Creator Marketplace 账号授权的访问令牌，参见[“从你的 TTO Creator Marketplace 账号获取授权和访问令牌”](1825117875361793.html)。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|tcm_account_id {必填}|string|TTO Creator Marketplace 账号的 ID。<br><br>若想接收针对与 TTO Creator Marketplace 账号关联的视频的 Spark Ads 推荐，请指定此字段。|
|video_ids|string[]|<ul><li>若想分析近一年与你的 TTO Creator Marketplace 账号关联的所有视频帖子，请勿传递 `video_ids` 和 `exclude_video_ids`。</li><li>若想缩小分析的视频帖子范围以生成推荐，需传递 `video_ids` 或 `exclude_video_ids`。<ul><li>每个视频帖子的推荐等级 (`recommendation_level`) 基于其所在的视频组得出。同一个视频放到不同的组中，可能会得到不同的推荐等级。</li></ul> </li></ul><br>仅包含需获取推荐结果的视频帖子的 ID 列表。<br><br>指定属于与 TTO Creator Marketplace 账号关联的 TTO 推广系列的视频帖子 ID。<br>若想获取属于 TTO 推广系列的帖子 ID，需使用 [/tto/tcm/report/](1815693573340162.html) 或 [/tto/tcm/campaign/](1815693562720258.html) 接口。<br><br>最大数量：100。|
|exclude_video_ids|string[]|<ul><li>若想分析近一年与你的 TTO Creator Marketplace 账号关联的所有视频帖子，请勿传递 `video_ids` 和 `exclude_video_ids`。</li><li>若想缩小分析的视频帖子范围以生成推荐，需传递 `video_ids` 或 `exclude_video_ids`。 </li></ul><br>仅包含不希望获取推荐结果的视频帖子的 ID 列表。<br><br>指定属于与 TTO Creator Marketplace 账号关联的 TTO 推广系列的视频帖子 ID。<br>若想获取属于 TTO 推广系列的帖子 ID，需使用 [/tto/tcm/report/](1815693573340162.html) 或 [/tto/tcm/campaign/](1815693562720258.html) 接口。<br><br>最大数量：100。|
|time|string|TikTok 视频帖子发布的时间。<br><br>枚举值：<ul><li>`PAST_ONE_MONTH`：近 1 个月。</li><li>`PAST_THREE_MONTHS`：近 3 个月。</li><li>`PAST_SIX_MONTHS`：近 6 个月。</li></ul><br>如果未传递此字段，系统将分析所有已发布（不论何时）的视频以生成推荐。<br><br><p><span style="color:darkred"><b>注意</b></span>：如果同时传递 `video_ids` 和 `time` 筛选条件，`time` 筛选条件将被忽略。但可同时使用 `exclude_video_ids` 和 `time` 筛选条件。|
|objective_type|string|用于生成推荐的推广目标。<br><br>枚举值：<ul><li>`REACH`：覆盖人数。</li><li>`TRAFFIC`：访问量。</li><li>`VIDEO_VIEWS`：视频播放量。</li><li>`APP_PROMOTION`：应用推广。</li><li>`LEAD_GENERATION`：线索收集。</li><li>`WEB_CONVERSIONS`：网站转化量。</li><li>`PRODUCT_SALES`：商品销量。</li></ul><br>如果未指定此字段，在生成推荐结果时将不会考虑推广目标。<br><br>如果指定此字段，可使用 [/campaign/create/](1739318962329602.html) 接口创建采用相同推广目标 (`objective_type`) 值的推广系列，并在调用 [/ad/create/](1739953377508354.html) 接口时将 `tiktok_item_id` 设置为其中一个推荐帖子 ID (`item_id`)，以便在广告中使用推荐视频帖子。|
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/spark_ad/recommend/?tcm_account_id={{tcm_account_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)。|
|request_id |string|请求的日志 ID，唯一标识一个请求。 |
|data |object|返回数据。|
#|videos|object|最多包含 100 个 TikTok 视频帖子的列表，并附有 Spark Ads 推荐结果。|
##|recommendation_level|string|推荐等级，表明视频帖子适合作为 Spark Ads 投放的程度。<br><br>枚举值： <ul><li>`HIGH`：强烈推荐。</li><li>`MEDIUM`：一般推荐。</li><li>`LOW`：不推荐。</li></ul>|
##|item_id|string|TikTok 视频帖子的唯一标识符。<br><br>你可以将此字段的值传递给 [/ad/create/](1739953377508354.html) 接口中的 `tiktok_item_id`，用于创建 Spark Ads。参见[“创建 Spark Ads”](1739470744631298.html)文档，详细了解 Spark Ads。<br><br>示例：`6995316737801538821`。<br><br>更新时间：实时|
##|creator_handle|string|上传视频帖子的达人的用户名。<br><br>更新时间：实时|
##|embed_url|string|此 TikTok 视频帖子的可嵌入链接。<br><br>示例：`https://www.tiktok.com/static/profile-video?id=7202758233486822657&hide_author=1&utm_campaign=tt4d_open_api&utm_source=7220548562860376066`。<br><br>更新时间：实时|
##|thumbnail_url|string|视频帖子缩略图的临时 URL。<br><br>URL 过期后需重新获取。URL 中包含过期时间，位于 `x-expires` 参数之后，格式为 Epoch/Unix 时间戳（单位：秒）。<br><br>示例：`https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/75dec21d63500917fb6ec8bc59415156~c5_300x300.jpeg?x-expires=1614099600&x-signature=PmK%2BWs3LzSzRL2tYs%2FZx7EjG3Gk%3D`。<br><br>更新时间：实时|
##|create_time|string|视频帖子发布时间，格式为 Epoch/Unix 时间戳（单位：秒，UTC 时间）。<br><br>示例：`1628461703`。<br><br>更新时间：实时|
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"videos": [
{
"create_time": "{{create_time}}",
"embed_url": "{{embed_url}}",
"handle_name": "{{handle_name}}",
"item_id": "{{item_id}}",
"recommendation_level": "HIGH",
"thumbnail_url": "{{thumbnail_url}}"
},
...,
{
"create_time": "{{create_time}}",
"embed_url": "{{embed_url}}",
"handle_name": "{{handle_name}}",
"item_id": "{{item_id}}",
"recommendation_level": "LOW",
"thumbnail_url": "{{thumbnail_url}}"
}
]
}
}
(/code)