← 返回目录
📁 API Reference › Spark Ads Using Authorized Posts

获取 Spark Ads 帖子列表

您可以使用本接口获取已授权给某一广告账户的 Spark Ads 帖子列表。

v1.2与v1.3版本对比

以下表格概括了 v1.2与v1.3接口的变化。 ``xtable |变化内容{20%}|v1.2{35%}|v1.3{45%}| |---|---|---| |接口路径|/v1.2/tt_video/list/|/v1.3/tt_video/list/| |请求参数类型|advertiser_id: number|advertiser_id: string| |新增请求参数| / |item_types| |返回参数名称|url(video_info中): string|preview_url(video_info中): string| |返回参数类型|invite_start_time: datetime<br>auth_end_time: datetime<br>auth_start_time: datetime<br>id(anchor_list中): number<br>item_id(item_info中): number|invite_start_time: string<br>auth_end_time:string<br>auth_start_time: string<br>id(anchor_list中): string<br>item_id(item_info中): string| |新增返回参数|/|url(anchor_list中) <br>item_type<br>carousel_info（包含本对象数组内的所有参数）<br>spu_id<br>spu_name<br>store_id`|



## 请求

**地址**  https://business-api.tiktok.com/open_api/v1.3/tt_video/list/

**方法** GET

**Header**

``` xtable
|字段|类型|描述|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。 |
|Content-Type {必填}|string|请求消息类型。<br>允许值: `"application/json"`。  |

参数

|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_id {必填}|string| 广告主 ID。 |
| item_types | string[] | 要筛选的 Spark Ads 帖子类型。<br><br> 枚举值：<ul><li>`VIDEO`：视频帖子。</li><li>`CAROUSEL`：照片帖子。</li></ul> <br> 默认值：`["VIDEO", "CAROUSEL"]`。 |
|keyword|string| 可以作为搜索TikTok帖子的关键词，可以为文本或TikTok帖子ID。 <br><br><ul><li>如果您想根据文本搜索TikTok帖子，提供最大长度为500个字符的文本字符串。这种搜索类型支持多语言搜索和模糊匹配。 <br>示例："summer"。</li><li> 如果你想根据`item_id`搜索TikTok帖子，提供最小长度为19个字符的数字字符串。这种搜索类型支持精确匹配。 <br>  示例："1234567891234567891" |
|page |number|当前页数。默认值: `1`，取值范围: ≥ 1。|
|page_size |number|分页大小。默认值: `20`，取值范围: 1-50。|

示例

(code curl http)
curl --get -H "Access-Token:xxx" \
--data-urlencode "advertiser_id=ADVERTISER_ID" \
--data-urlencode "page=PAGE" \
--data-urlencode "page_size=PAGE_SIZE" \
https://business-api.tiktok.com/open_api/v1.3/tt_video/list/
(/code)

返回

|字段{37%}|类型{13%}|描述{50%}|
|---|---|---|
|code |number|返回码。完整返回码列表及描述，可查看[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息。更多信息可查看[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。 |
|data |object|返回数据。  |
#|list |object[]|Spark Ads 帖子列表信息。  |
##|item_info |object| Spark Ads 帖子信息。 |
###|auth_code |string| Spark Ads 帖子授权码。 |
###|item_id |string| Spark Ads 帖子ID。 |
###|text |string| Spark Ads 帖子描述。 |
###|status | string | 帖子状态。枚举值参见[枚举值-TikTok帖子状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。 |
###| item_type | string | Spark Ads 帖子类型。 <br><br>枚举值：<ul><li>`VIDEO`：视频帖子。 </li><li>`CAROUSEL`：照片帖子。 </li></ul> |
###| carousel_info | object | 照片帖子信息。<br><br><p><span style="color:darkred"><b>注意</b></span>：`item_type` 为 `VIDEO` 时，本字段值为 null。 |
####| image_info | object[] | 照片帖子中使用的图片的信息。<br>图片返回的顺序与在照片帖子中的顺序一致。 |
#####| 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 应用中直接发布且无音乐的帖子，则本字段的值将为 null 。 |
#####| music_url | string | 音乐 URL。<br><br>有效期：90 天。 |
#####| music_duration | integer | 音乐时长，单位为秒。|
###|anchor_list | object []|Spark Ads 帖子中的锚点列表。 |
####|id|string | 锚点 ID。 |
####|title |string | 锚点标题。 |
####|status  | string | 锚点状态。枚举值: `CHECK_ING` (锚点正在审核中), `CHECK_FAILED` (锚点审核未通过), `CHECK_SUCCESS` (锚点审核已通过)。 |
####|product_regions |string[] | 广告可投放区域。|
####|url| string | 帖子 URL。 |
####| spu_id | string | 仅当帖子中包含商品锚点链接时返回本字段。 <br><br>该帖子绑定的商品的 SPU ID。 |
####| spu_name | string | 仅当帖子中包含商品锚点链接时返回本字段。 <br><br>该帖子绑定的商品的名称。|
####| store_id | string | 仅当帖子中包含商品锚点链接时返回本字段。 <br><br>商品所属的 TikTok Shop 的 ID。 |
##|video_info |object| 视频帖子信息。<br><br><p><span style="color:darkred"><b>注意</b></span>： <ul><li>`item_type` 为 `CAROUSEL` 时，`video_info` 对象中的字段值为 null。</li><li>`item_type` 为 `VIDEO` 且 `status` 非`HESITATE_RECOMMEND`，`ONLY_AUTHOR_SEE` 或 `ONLY_FRIEND_SEE` 时，`video_info` 对象中的字段将无数据，这些字段的值将为 null，`0` 或 `""` （空字符串）。</li></ul> |
###|bit_rate |integer|视频比特率，单位为位/秒。  |
###|duration |float|视频时长，单位秒。  |
###|size |integer|视频大小，单位Byte。 |
###|width |integer|视频宽度。  |
###|height |integer|视频高度。  |
###|poster_url |string|视频封面URL。 有效期1小时，过期需重新获取。  |
###|preview_url |string|视频预览URL。 有效期1小时，过期需重新获取。<br><p><span style="color:darkred"><b>注意</b></span>：若授权失效或TikTok帖子状态（`item_info`下`status`的值）非`HESITATE_RECOMMEND`（公开可见），则本字段返回空字符串`""`。TikTok帖子状态的枚举值参见[枚举值-TikTok帖子状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。  |
###|signature |string|视频文件MD5。  |
##|user_info |object| TikTok 账户信息。 |
###|tiktok_name |string| TikTok 账户昵称。 |
###|identity_id |string| 认证身份ID。 |
###|identity_type |string| 认证身份类型。 |
##|auth_info |object| 授权信息。 |
###|invite_start_time |string| 授权起始时间(UTC+0)。时间格式：2017-01-01 00:00:00。 |
###|auth_start_time |string| 授权码有效期开始时间(UTC+0)。时间格式：2017-01-01 00:00:00。 |
###|ad_auth_status |string| 授权状态。枚举值参见 [枚举值-TikTok帖子授权状态](https://ads.tiktok.com/marketing_api/docs?id=1737174886619138)。|
###|auth_end_time |string| 授权码有效期结束时间(UTC+0)。时间格式：2017-01-01 00:00:00。 |
#|page_info |object | 分页信息。 |
##|page |number | 当前页数。 |
##|page_size |number | 分页大小。 |
##|total_number |number | 总结果数。 |
##|total_page |number | 总页数。 |
|request_id |string|请求的日志ID，唯一标识一个请求。  |

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "xxx",
    "data": {
        "page_info": {
            "total_page": 15,
            "total_number": 300,
            "page": 1,
            "page_size": 20
        },
        "list": [
            {
                "user_info": {
                    "tiktok_name": "{{tiktok_name}}",
                    "identity_id": "{{identity_id}}",
                    "identity_type": "AUTH_CODE"
                },
                "item_info": {
                    "anchor_list": [
                        {
                            "id": "{{id}}",
                            "status": "CHECK_FAILED",
                            "product_regions": [
                                "ID"
                            ],
                            "url": "",
                            "title": "{{title}}"
                        }
                    ],
                    "text": "{{text}}",
                    "status": "HESITATE_RECOMMEND",
                    "auth_code": "{{auth_code}",
                    "item_id": "{{item_id}}",
                    "item_type": "VIDEO",
                    "carousel_info": null
                },
                "auth_info": {
                    "auth_start_time": "2021-05-23 11:26:45",
                    "ad_auth_status": "AUTHORIZED",
                    "invite_start_time": "2021-05-23 11:28:02",
                    "auth_end_time": "2022-07-22 11:26:45"
                },
                "video_info": {
                    "duration": 8.081,
                    "preview_url": "{{preview_url}}",
                    "bit_rate": {{bit_rate}},
                    "height": {{height}},
                    "width": {{width}},
                    "signature": "{{signature}}",
                    "size": 2379969,
                    "poster_url": "{{poster_url}}"
                }
            },
            ...
           ]
}
(/code);
← 应用授权码解除 Spark Ads 帖子绑定 →

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