获取 TTO 公开媒体表现数据
你可以使用本接口获取 TikTok One (TTO) Creator Marketplace 中达人视频的信息。
TCM 与 TTO Creator Marketplace接口对比
以下表格概括了 TikTok Creator Marketplace（TCM）与 TTO Creator Marketplace 接口的变化。
| 变化内容 {24%}| TCM 接口{36%} | TTO Creator Marketplace接口{40%} |
|---|---|---|
| 接口路径 | /v1.3/tcm/creator/public/video/list/| /v1.3/tto/tcm/creator/public/video/list/ |
| 相同请求参数 | `video_ids`<br>`cursor`<br>`limit` | `video_ids`<br>`cursor`<br>`limit` |
| 废弃请求参数 | N/A | `creator_id` |
| 新增请求参数 | N/A | `tto_tcm_account_id`<br>`handle_name` |
| 相同返回参数 | `posts`<br>`posts.video_id`<br>`posts.caption`<br>`posts.likes`<br>`posts.comments`<br>`posts.shares`<br>`posts.video_views`<br>`posts.embed_url`<br>`posts.thumbnail_url`<br>`posts.create_time`<br>`posts.display_name`<br>`page_info`<br>`page_info.has_more`<br>`page_info.cursor` | `posts`<br>`posts.video_id`<br>`posts.caption`<br>`posts.likes`<br>`posts.comments`<br>`posts.shares`<br>`posts.video_views`<br>`posts.embed_url`<br>`posts.thumbnail_url`<br>`posts.create_time`<br>`posts.display_name`<br>`page_info`<br>`page_info.has_more`<br>`page_info.cursor` |
| 废弃请求参数 | N/A | `posts.engagement_count`<br>`posts.engagement_rate` |
| 新增返回参数 | N/A | `posts.favorites` |
请求
地址 https://business-api.tiktok.com/open_api/v1.3/tto/tcm/creator/public/video/list/
方法 GET
Header
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|由 TTO Creator Marketplace 账户授权的访问令牌。<br>详情参见[从 TTO Creator Marketplace 账户获取授权和访问令牌](https://business-api.tiktok.com/portal/docs/obtain-authorization-and-authentication-from-a-tto-creator-marketplace-account/v1.3)。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|tto_tcm_account_id {必填}|string|TTO Creator Marketplace 账户的 ID。<br><br>要获取您通过访问令牌 `Access-Token` 可访问的账户 ID，可使用接口 [/tto/oauth2/tcm/](1815693478150146.html)。|
|handle_name {必填}|string|您想要搜索的 TTO 创作者市场创作者的用户名。<br><br>支持精确匹配。<br><br><span style="color:darkred"><b>注意</b></span>：如果您指定的账号用户名尚未加入 TTO Creator Marketplace，将会出现报错。|
|video_ids|string[]|用于筛选结果的视频 ID 列表。<br><br>最大数量：25。<br><br>如果未指定此字段，结果将不按视频 ID 进行筛选。|
|cursor|number|要检索后续视频的视频时间戳游标。<br><br>如果返回的字段 `has_more` 为 `true`，在下一次请求中将返回的`cursor`传入此参数，以获取后续视频。<br><br>默认值：0。默认返回最新的视频。|
|limit|number|每次请求返回的帖子数量。<br><br>取值范围：1-25。<br><br>默认值：10。|
示例
(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/tto/tcm/creator/public/video/list/?tto_tcm_account_id={{tto_tcm_account_id}}&handle_name={{handle_name}}' \
--header 'Access-Token: {{access_token}}' \
(/code)
返回
|Field{30%}|Type{15%}|Description{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|返回数据。|
#|posts|object[]|创作者的公开视频列表。|
##|display_name|string|创作者的显示名称。|
##|video_id|string|视频的唯一标识符。<br><br>示例：`1234567890`。|
##|thumbnail_url|string|视频缩略图的临时 URL。<br><br>有效期：约七天。<br><br>URL 中的 `x-expires` 参数后包含过期时间，格式为以秒为单位的 Epoch/Unix 时间戳。<br><br>URL 过期后，您需要调用 [/tto/tcm/creator/public/video/list/](1828185411810305.html) 获取新的 URL。|
##|embed_url|string|该 TikTok 视频的可嵌入链接。该 URL 可用于在外部网站或应用中嵌入 TikTok 视频。<br><br>如果帖子的隐私设置为“好友可见”或“仅自己可见”，则无法通过此链接观看视频。|
##|caption|string|视频描述。|
##|likes|integer|点赞数。<br>视频的总点赞数。<br><br>示例：100。|
##|comments|integer|评论数。<br>视频的总评论数。<br><br>示例：100。|
##|shares|integer|分享数。<br>视频被分享的总次数。<br><br>示例：100。|
##|favorites|integer|收藏数。<br>视频被添加到收藏的总次数。<br><br>示例：100。|
##|video_views|integer|视频观看次数。<br>观看该视频的次数。<br><br>示例：100。<br><br><span style="color:darkred"><b>注意</b></span>：重复观看不计入统计。|
##|create_time|string|视频创建时间，Unix/epoch 时间戳，单位为毫秒（UTC+0 时间）。<br><br>示例：`1743090990000`。|
##|caption_hashtags|string[]|帖子文案中出现的标签列表。
##|mentioned_accounts|string[]|帖子文案中提及（@）的 TikTok 账号的显示名称列表。
##|collaboration_status|string|一个状态，指示该帖是否用于品牌内容。<br><br>枚举值：<ul><li>`PAID_PARTNERSHIP`：TTO 营销活动链接关联的帖子。</li><li>`CREATOR_EARNS_COMMISSION`：TikTok 店铺的创作者通过联盟链接获得佣金，点击[此处](https://ads.tiktok.com/help/article/faqs-affiliate-creatives-authorization?lang=zh)了解更多。</li><li>`NONE`</li>
#|page_info|object|分页信息。|
##|has_more|boolean|是否还有更多视频。<br><br>支持值：`true`、`false`。|
##|cursor|integer|标记当前请求返回的最后一个视频时间戳游标。<br><br>如果返回的 `has_more` 为 `true`，您可以在后续请求中将该值传入 `cursor` 参数，以获取后续帖子。<br><br>示例：`1734031433000`。|
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "{{request_id}}",
"data": {
"page_info": {
"cursor": 1734031433000,
"has_more": false
},
"posts": [
{
"caption": "{{caption}}",
"comments": 0,
"create_time": "1734031433000",
"display_name": "{{display_name}}",
"embed_url": "{{embed_url}}",
"favorites": 0,
"likes": 3,
"shares": 1,
"thumbnail_url": "{{thumbnail_url}}",
"video_id": "{{video_id}}",
"video_views": 236
}
]
}
}
(/code)