获取广告发布身份下的帖子
此接口可用于获取某个广告发布身份下的所有帖子。
v1.2 与 v1.3 接口对比
下表概述了 v1.2 接口与 v1.3 接口之间的差异。
|变更{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径| /v1.2/identity/video/get/| /v1.3/identity/video/get/|
| 请求参数类型 | `advertiser_id`: number | `advertiser_id` : string |
| 新增请求参数 | / | `item_type`<br>`exclude_adsonly` |
| 返回参数名称 | `list`| `video_list`|
| 返回参数类型 | `cursor` : number <br> `item_id` : number <br>| `cursor` : string <br>`item_id` : string|
| 返回参数名称和类型 | `id` : number |`anchor_id` : string |
| 新增返回参数 | / | `item_type` <br>`carousel_info`（包括对象内的所有参数） |
请求
地址
https://business-api.tiktok.com/open_api/v1.3/identity/video/get/
方法 GET
Header
|字段|类型|描述|
|---|---|---|
|Access-Token{必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
参数
|字段|类型|描述|
|---|---|---|
| advertiser_id {必填} | string | 广告主 ID。 |
| identity_id {必填} | string | 广告发布身份 ID。|
| identity_type {必填} | string | 广告发布身份类型。枚举值：`AUTH_CODE`、`TT_USER`、`BC_AUTH_TT`。详细信息参见[认证身份](https://ads.tiktok.com/marketing_api/docs?id=1738958351620097)。 |
| identity_authorized_bc_id{+条件必填} | string | 与“添加到商务中心的 TikTok 用户”类型广告发布身份关联的商务中心 ID。当 `identity_type` 为 `BC_AUTH_TT` 时，此为必填字段。 |
| item_type | string | 要获取的 TikTok 帖子的类型。<br><br>枚举值： <ul><li> `VIDEO`：视频帖子。 </li><li>`CAROUSEL`：图片帖子。 </li></ul><br>默认值：`VIDEO`。 |
|keyword|string| 仅当 `identity_type` 设置为 `AUTH_CODE` 时生效。否则系统将报错。<br><br>用于搜索 TikTok 帖子的关键词，可为文本或 TikTok 帖子 ID。<br><br><ul><li>若想基于文本搜索 TikTok 帖子，需提供长度不超过 500 个字符的文本字符串。这一搜索类型支持多语言搜索和模糊匹配。<br> 示例："summer"。</li><li> 若想基于 `item_id` 搜索 TikTok 帖子，需提供长度不少于 19 个字符的数字字符串。这一搜索类型支持精确匹配。<br> 示例："1234567891234567891" |
|exclude_adsonly|boolean|是否从结果中排除仅通过广告显示的帖子。<br>仅通过广告显示的帖子是指通过 TikTok 账号发布为广告、不显示在账号主页上的帖子。<br><br>支持的值：<ul><li>`false`：获取自然流量帖子和仅通过广告显示的帖子。</li><li>`true`：最多可获取 500 个近期发布的自然流量帖子。</li></ul><br>默认值：`false`。|
| cursor | integer | 分页光标。|
| count | number | 要获取的 TikTok 帖子数量。<br><br>值范围：1-20。<br>如果传入的值大于 20，此字段将被忽略，并最多返回 20 个与该广告发布身份关联的 TikTok 帖子。|
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/identity/video/get/?advertiser_id={{advertiser_id}}&identity_type=TT_USER&identity_id={{identity_id}}' \
--header 'Access-Token: {{Access-Token}}'
(/code)
返回
|字段|类型|描述|
|---|---|---|
|code |number | 返回码。完整返回码列表及描述参见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string | 返回信息。更多信息参见[附录 - 返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data |object| 返回数据。 |
#| cursor | string | 时间戳光标或分页光标。<ul><li>如果 `identity_type` 为 `TT_USER` 或 `BC_AUTH_TT`：<ul><li>当请求中的 `exclude_adsonly` 为 `false` 时，`cursor` 为当前请求返回的最后一个帖子的时间值。你需要在后续请求中使用此光标值获取下一个帖子。</li><li>当请求中的 `exclude_adsonly` 为 `true` 时，`cursor` 为分页光标。如果返回结果中的 `has_more` 为 `true`，在后续请求中使用返回的 `cursor` 获取下一页结果。</li></ul></li><li>如果 `identity_type` 为 `AUTH_CODE`，`cursor` 为分页光标。如果返回结果中的 `has_more` 为 `true`，在后续请求中使用返回的 `cursor` 获取下一页结果。</li></ul> |
#| has_more | boolean | 是否有更多可用数据。 |
#| video_list | object[] | 帖子列表。 |
##| item_type | string | TikTok 帖子类型。<br><br>枚举值： <ul><li> `VIDEO`：视频帖子。 </li><li>`CAROUSEL`：图片帖子。 </li></ul>|
##| item_id | string | TikTok 帖子 ID。 |
##| status | string | TikTok 帖子状态。<br><br>枚举值：<ul><li> `ITEM_STATUS_HESITATE_RECOMMEND`：对所有人可见。 </li><li>`STATUS_ONLY_FRIEND_SEE`：对好友可见。</li><li>`ITEM_STATUS_ONLY_AUTHOR_SEE`：私密。</li></ul> |
##| text | string | TikTok 帖子的文本内容。 |
##| auth_info | object | 授权信息。 |
###| ad_auth_status | string | 授权状态。 |
###| auth_end_time | string | 授权码的生效时间 (UTC+0)，格式为 2017-01-01 00:00:00。 |
###| auth_start_time | string | 授权码的生效时间（时区：UTC+0），格式为 2017-01-01 00:00:00。 |
###| invite_start_time| string | 授权开始生效的时间 (UTC+0)，格式为 2017-01-01 00:00:00。 |
##| anchor_list | object | 锚点相关信息。 |
###| anchor_id | string | 锚点 ID。 |
###| title | string | 锚点标题。 |
###| status | string | 锚点状态。枚举值：`CHECK_ING`、`CHECK_FAILED`、`CHECK_SUCCESS`。 |
###| url | string | 锚点 URL。 |
###| product_regions | string[] | 广告可投放的地区。此为国家或地区代码列表。例如：`["DE"]`。 |
##| video_info | object | 视频帖子相关信息。<br><br><p><span style="color:darkred"><b>注意</b></span>：当 `item_type` 为 `CAROUSEL` 时，此字段的值将为空。 |
###| bit_rate | integer| 比特率，以 bps 为单位。 |
###| duration | float | 视频时长，以秒为单位。 |
###| size | integer | 视频大小，以字节为单位。 |
###| height | integer | 视频高度。 |
###| width | integer| 视频宽度。 |
###| poster_url | string | 视频封面图片 URL。<br>URL 中包含过期时间，位于 `x-expires` 参数之后，格式为 Epoch/Unix 时间戳（单位：秒）。 <br>URL 过期后，需要调用此接口获取新的 URL。 |
###| signature | string | 视频文件的 MD5。 |
###| url | string | 视频预览链接。<br>链接有效期为 1 小时。 <br>URL 过期后，需要再次调用此接口获取新的 URL。 |
###| format | string | 视频格式。 |
##| carousel_info | object | 图片帖子相关信息。 <br> <br><p><span style="color:darkred"><b>注意</b></span>：当 `item_type` 为 `VIDEO` 时，此字段的值将为空。 |
###| image_info | object[] | 用于图片帖子的图片相关信息。<br><br>图片会按照其在图片帖子中的显示顺序返回。 |
####| image_id | string | 图片 ID。 |
####| image_url | string | 图片 URL。<br><br>有效期：90 天。 |
####| image_height | integer | 图片高度，以像素为单位。 |
####| image_width | integer| 图片宽度，以像素为单位。 |
###| music_info | object | 用于图片帖子的音乐相关信息。 <br> <br><p><span style="color:darkred"><b>注意</b></span>：如果图片帖子在 TikTok 应用中直接发布且不包含音乐，此字段的值将为空。 |
####| music_id | string | 音乐 ID。 |
####|music_url | string | 音乐 URL。<br><br>有效期：90 天。 |
####| music_duration |integer | 音乐时长，以秒为单位。 |
|request_id|string|请求的日志 ID，唯一标识一个请求。 |
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"cursor": "1780432720000",
"has_more": true,
"video_list": [
{
"anchor_list": null,
"auth_info": null,
"carousel_info": null,
"item_id": "{{item_id}}",
"item_type": "VIDEO",
"status": "ITEM_STATUS_HESITATE_RECOMMEND",
"text": "{{text}}",
"video_info": {
"bit_rate": 15184988,
"duration": 13.8,
"format": "mp4",
"height": 1920,
"poster_url": "{{poster_url}}",
"signature": "{{signature}}",
"size": 26194106,
"url": "{{url}}",
"width": 1080
}
},
{
"anchor_list": null,
"auth_info": null,
"carousel_info": null,
"item_id": "{{item_id}}",
"item_type": "VIDEO",
"status": "ITEM_STATUS_HESITATE_RECOMMEND",
"text": "{{text}}",
"video_info": {
"bit_rate": 990999,
"duration": 16,
"format": "mp4",
"height": 1280,
"poster_url": "{{poster_url}}",
"signature": "{{signature}}",
"size": 1981998,
"url": "{{url}}",
"width": 720
}
}
]
}
}
(/code)