获取商品 GMV Max 推广系列可用的帖子
您可以使用本接口获取使用了某一 TikTok Shop 的商品 GMV Max 推广系列中可用的 TikTok 帖子列表。
请求
地址 https://business-api.tiktok.com/open_api/v1.3/gmv_max/video/get/
方法 GET
Header
|字段{36%}|类型{12%}|描述{52%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。<br>可以通过[获取访问令牌](1738373164380162.html)接口获取。|
参数
|字段{36%}|类型{12%}|描述{52%}|
|---|---|---|
| advertiser_id {必填} | string | 广告主 ID。 |
| store_id {必填} | string | TikTok Shop ID。<br><br> 若想获取可用于 GMV Max 推广系列的 TikTok Shop，可使用 [/gmv_max/store/list/](1822001044479041.html) 并确认返回的 `is_gmv_max_available` 为 `true`。 |
| store_authorized_bc_id {必填} | string |有权限访问该 TikTok Shop（`store_id`）的商务中心的 ID。 |
| spu_id_list | string[] |用于筛选结果的商品 SPU（标准化产品单元）ID 列表。<br><br> <ul><li>若您想在商品 GMV Max 推广系列中使用已授权的作品推广此 TikTok Shop 的所有商品，无需传入 `spu_id_list` 和 `custom_posts_eligible` 本字段。 </li><li>若您想在商品 GMV Max 推广系列中使用已授权的作品推广此 TikTok Shop 的特定商品，需通过 `spu_id_list` 本字段指定这些商品，无需传入 `custom_posts_eligible`。 </li><li>若您想在商品 GMV Max 推广系列中使用自定义的作品推广此 TikTok Shop 的某个商品，需通过 `spu_id_list` 字段指定该商品，并将 `custom_posts_eligible` 设置为 `true`。 </li></ul><br>最大数量： <ul><li>当 `custom_posts_eligible` 为 `false` 或未传入时：50。 </li><li>当 `custom_posts_eligible` 为 `true` 时：1。 </li></ul><br>若想获取某个 TikTok Shop 中商品的 SPU ID 列表，可使用[/store/product/get/](1793482248880130.html)。将 `ad_creation_eligible` 设置为 `GMV_MAX` 并从返回中挑选 `status` 为 `AVAILABLE` 且 `gmv_max_ads_status` 为 `UNOCCUPIED` 的 `item_group_id` 值。 |
| custom_posts_eligible | boolean | 是否请求用于自定义的作品中推广某个商品的视频。<br><br>若您将本字段设置为 `true`，您需同时通过 `spu_id_list` 指定一个商品。<br><br>支持的值：`true`，`false`。<br>默认值：`false`。 |
| sort_field | string | 仅当 `custom_posts_eligible` 为 `false` 或未传入时生效。<br><br>对用于自定义的作品的视频的排序字段。<br><br>枚举值:<ul><li>`GMV`：商品交易总额。</li><li>`POST_TIME`：发布时间。</li><li>`VIDEO_VIEWS`：视频播放量。</li><li>`VIDEO_LIKES`：视频点赞数。</li><li>`CLICK_THROUGH_RATE`：点击率。</li><li>`PRODUCT_CLICKS`：商品点击次数。</li></ul>默认值：`GMV`。 |
| sort_type | string | 对用于已授权的作品或自定义的作品的视频的排序顺序。<br><br>枚举值:<ul><li>`ASC`：升序。</li><li>`DESC`：降序。</li></ul>默认值：`DESC`。<br><br><ul><li>若 `custom_posts_eligible` 为 `false` 或未传入，您可通过同时指定 `sort_field` 和 `sort_type` 对用于已授权的作品的视频排序。</li><li>若 `custom_posts_eligible` 为 `true`，您无需指定 `sort_field`。在此情况下，默认对用于自定义的作品的视频按发布时间降序排序，最先返回最近发布的作品。若您希望按升序排序（最先返回最早发布的作品），可手动将 `sort_type` 设置为 `ASC`。</li></ul> |
| keyword | string | 用于筛选帖子（视频）的搜索关键词。<br><br>您可指定帖子 ID 或文案。<br><br><ul><li>若您想根据文案（`text`）搜索帖子，可提供一个文本字符串。这种搜索类型支持多语言搜索和模糊匹配。<br>示例：`summer`。</li><li>若您想根据帖子 ID（`item_id`）搜索帖子，需提供最小长度为 19 个字符的数字字符串。这种搜索类型支持精确匹配。<br>示例：`1234567891234567891`。</li></ul>|
| need_auth_code_video| boolean| 是否在结果中包含与 `AUTH_CODE` 类型的认证身份绑定的帖子。<br><br> 支持的值： `true`，`false`。<br>默认值：`false`。<br><br><p><span style="color:darkred"><b>注意</b></span>：若未传入 `need_auth_code_video` 或设置为 `false` 且未传入 `identity_list`，返回的结果将为空。|
| identity_list | object[] | 用于筛选结果的 `TT_USER`、`BC_AUTH_TT` 或 `TTS_TT` 认证身份列表。<br><br>若想获取可用于商品 GMV Max 推广系列的认证身份列表，可使用 [/gmv_max/identity/get/](1822001101474882.html)并确认返回的 `product_gmv_max_available` 为`true`。<br><br>最大数量：20。<br><br><p><span style="color:darkred"><b>注意</b></span>：若未传入 `need_auth_code_video` 或设置为 `false` 且未传入 `identity_list`，返回的结果将为空。|
#| identity_id | string | 认证身份 ID。|
#| identity_type | string | 认证身份类型。 <br><br>枚举值： <ul><li>`AUTH_CODE`：授权用户。当您使用授权码访问 TikTok 账户或 TikTok 帖子时，系统将创建此类型的认证身份。</li><li>`TT_USER`：TikTok 用户。当您绑定 TikTok For Business 账户与 TikTok 企业号，或将 TikTok For Business 账户与普通 TikTok 账户绑定后，将 TikTok 账户升级为企业号时，系统将创建此类型的认证身份。</li><li>`BC_AUTH_TT`：添加到商务中心的 TikTok 用户。当您将 TikTok 账号添加到商务中心，并从 TikTok 账号主获得访问批准后，系统将创建此类型的认证身份。 </li><li>`TTS_TT`：TikTok Shop 关联的 TikTok 用户。当您为 TikTok Shop 设置官方 TikTok 账号后，系统将创建此类型的认证身份。</li></ul> |
#| identity_authorized_bc_id {+条件必填} | string |仅当 `identity_type` 为 `BC_AUTH_TT` 时，本字段必填。<br><br> 与添加到商务中心的 TikTok 用户类型认证身份绑定的商务中心的 ID。 |
#| identity_authorized_shop_id {+条件必填} | string | 仅当 `identity_type` 为 `BC_AUTH_TT` 且[/gmv_max/identity/get/](1822001101474882.html)为此认证身份返回了 `identity_authorized_shop_id` 字段时，本字段必填。<br><br>与添加到商务中心的 TikTok 用户类型认证身份绑定的 TikTok Shop 的 ID。|
#| store_id {+条件必填} | string | 仅当 `identity_type` 为 `TTS_TT` 时，本字段必填。 <br><br>与 TikTok Shop 关联的 TikTok 用户类型认证身份绑定的 TikTok Shop 的 ID。|
| page | number | 当前页数。<br><br>取值范围： ≥ 1。<br>默认值：1。|
| page_size | number | 页面大小。<br><br> 取值范围：1-50。<br> 默认值：10。 |
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/gmv_max/video/get/?advertiser_id={{advertiser_id}}&store_id={{store_id}}&store_authorized_bc_id={{store_authorized_bc_id}}&need_auth_code_video=true&identity_list=[{ "identity_type": "BC_AUTH_TT","identity_id": "{{identity_id}}","identity_authorized_bc_id": "{{identity_authorized_bc_id}}"}]&page=1&page_size=50' \
--header 'Access-Token: {{Access-Token}}'
(/code)
返回
|字段{36%}|类型{12%}|描述{52%}|
|---|---|---|
|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| 返回数据。 <br><br><p><span style="color:darkred"><b>注意</b></span>：若本字段返回空列表，可遵循以下步骤将带有商品链接的帖子授权给广告账户：<br>1. 使用 [/tt_video/authorize/](1738376435339265.html) 将帖子授权给广告账户。<br>2. 使用 [/tt_video/info/](1738376324021250.html) 或 [/tt_video/list/](1738376465972226.html) 检查帖子是否带有商品信息（`spu_id`、`spu_name` 和 `store_id`）。</p>|
#| item_list| object[] | 使用该 TikTok Shop 的商品 GMV Max 推广系列中可用的 TikTok 视频（帖子）列表 。|
##| item_id | string |TikTok 帖子 ID。 |
##| text | string | TikTok 帖子描述。 |
##| spu_id_list| string[] | 与该 TikTok 帖子绑定的商品 SPU ID 列表。 <br><br><p><span style="color:darkred"><b>注意</b></span>：无商品锚点链接的视频将不会返回本字段。|
##| can_change_anchor | boolean | 是否支持更改视频中的商品锚点链接。<br><br>支持的值：<ul><li>`true`：您可在此视频中新增商品锚点链接创建自定义的作品。</li><li>`false`：不支持使用此视频创建自定义的作品。</li></ul><br><p><span style="color:darkred"><b>注意</b></span>：若 `can_change_anchor` 为 `false`，则不支持将本字段传入 [/campaign/gmv_max/create/](1822000988713089.html) 或 [/campaign/gmv_max/update/](1822001009002497.html) 中的 `custom_anchor_video_list` 或 `item_list` 创建自定义的作品。 |
##| identity_info | object | 与该 TikTok 帖子绑定的认证身份的有关信息。 |
###| identity_id | string | 认证身份 ID。|
###| identity_type | string | 认证身份类型。 <br><br>枚举值： <ul><li>`AUTH_CODE`：授权用户。当您使用授权码访问 TikTok 账户或 TikTok 帖子时，系统将创建此类型的认证身份。.</li><li>`TT_USER`：TikTok 用户。当您绑定 TikTok For Business 账户与 TikTok 企业号，或将 TikTok For Business 账户与普通 TikTok 账户绑定后，将 TikTok 账户升级为企业号时，系统将创建此类型的认证身份。</li><li>`BC_AUTH_TT`：添加到商务中心的 TikTok 用户。当您将 TikTok 账号添加到商务中心，并从 TikTok 账号主获得访问批准后，系统将创建此类型的认证身份。 </li><li>`TTS_TT`：TikTok Shop 关联的 TikTok 用户。当您为 TikTok Shop 设置官方 TikTok 账号后，系统将创建此类型的认证身份。 </li></ul> |
###| identity_authorized_bc_id | string | 仅当 `identity_type` 为 `BC_AUTH_TT` 时返回本字段。<br><br>与添加到商务中心的 TikTok 用户类型认证身份绑定的商务中心的 ID。|
###| identity_authorized_shop_id | string | 仅为部分 `BC_AUTH_TT` 认证身份返回本字段。<br><br>与添加到商务中心的 TikTok 用户类型认证身份绑定的 TikTok Shop 的 ID。 |
###| store_id | string | 仅当 `identity_type` 为 `TTS_TT` 时返回本字段。 <br><br>与 TikTok Shop 关联的 TikTok 用户类型认证身份绑定的 TikTok Shop 的 ID。 |
###| profile_image | string | 与该认证身份绑定的 TikTok 账号的主页头像临时 URL。 <br><br>有效期：约 48 小时。过期时间包含在 `x-expires` 参数后的 URL 中，格式为以秒为单位的 Epoch/Unix 时间戳。<br><br>URL 过期后，您需要调用 [/campaign/gmv_max/info/](1822000968821762.html) 获取新的 URL。|
###| user_name| string | 与该认证身份绑定的 TikTok 账号的用户名。 |
##| video_info | object | 帖子中视频的详情。|
###| video_id | string | 视频 ID。 |
###| video_cover_url | string | 视频封面的临时 URL。<br><br>有效期：约 24 小时。过期时间包含在 `x-expires` 参数后的 URL 中，格式为以秒为单位的 Epoch/Unix 时间戳。 <br><br> URL 过期后，您需要调用[/campaign/gmv_max/info/](1822000968821762.html)获取新的 URL。 |
###| preview_url | string | 视频的临时预览 URL。<br><br> 有效期：6 小时。<br><br>URL 过期后，您需要调用[/campaign/gmv_max/info/](1822000968821762.html)获取新的 URL。 |
###| height | number | 视频的高度，单位为像素。 <br><br> 示例：1920。 |
###| width | number | 视频的宽度，单位为像素。<br><br>示例：1080。 |
###| bit_rate | number | 视频的码率，单位为 bps。 <br><br>示例：8500323。 |
###| duration | number | 视频的时长，单位为秒。 <br><br>示例：3.669。 |
###| size | number | 视频文件的大小，单位为 byte。<br><br>示例：3898461。 |
###| signature | string | 视频文件的 MD5 值。 <br><br>示例：`ab1cd2345e678fghi91jkl23b456m7no`。 |
###| format | string | 视频的格式。<br><br>示例：`mp4`。|
###| definition | string | 视频的清晰度。<br><br>示例：`1080p`。 |
###| fps | number | 视频的每秒帧数（FPS）。<br><br> 示例：27。 |
#| page_info | object | 分页信息。 |
##| page | number | 当前页数。 |
##| page_size | number | 分页大小。 |
##| total_number | number | 总结果数。 |
##| total_page | number | 总页数。 |
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"item_list": [
{
"identity_info": {
"display_name": "{{display_name}}",
"identity_id": "{{identity_id}}",
"identity_type": "AUTH_CODE",
"profile_image": "{{profile_image}}"
},
"item_id": "{{item_id}}",
"spu_id_list": [
"{{spu_id}}"
],
"text": "{{text}}",
"video_info": {
"bit_rate": 8500323,
"definition": "1080p",
"duration": 3.669,
"format": "mp4",
"fps": 30,
"height": 1920,
"preview_url": "{{preview_url}}",
"signature": "{{signature}}",
"size": 3898461,
"video_cover_url": "{{video_cover_url}}",
"video_id": "{{video_id}}",
"width": 1080
}
},
{
"identity_info": {
"display_name": "{{display_name}}",
"identity_id": "{{identity_id}}",
"identity_type": "AUTH_CODE",
"profile_image": "{{profile_image}}"
},
"item_id": "{{item_id}}",
"spu_id_list": [
"{{spu_id}}"
],
"text": "{{text}}",
"video_info": {
"bit_rate": 109400,
"definition": "540p",
"duration": 5.256,
"format": "mp4",
"fps": 27,
"height": 1024,
"preview_url": "{{preview_url}}",
"signature": "{{signature}}",
"size": 71876,
"video_cover_url": "{{video_cover_url}}",
"video_id": "{{video_id}}",
"width": 576
}
},
{
"identity_info": {
"display_name": "{{display_name}}",
"identity_authorized_bc_id": "{{identity_authorized_bc_id}}",
"identity_id": "{{identity_id}}",
"identity_type": "BC_AUTH_TT",
"profile_image": "{{profile_image}}"
},
"item_id": "{{item_id}}",
"spu_id_list": [
"{{spu_id}}"
],
"text": "{{text}}",
"video_info": {
"bit_rate": 164638,
"definition": "540p",
"duration": 5,
"format": "mp4",
"fps": 30,
"height": 1024,
"preview_url": "{{preview_url}}",
"signature": "{{signature}}",
"size": 107982,
"video_cover_url": "{{video_cover_url}}",
"video_id": "{{video_id}}",
"width": 576
}
}
],
"page_info": {
"page": 1,
"page_size": 50,
"total_number": 3,
"total_page": 1
}
}
}
(/code)