发现 TTO 达人

你可以使用本接口搜索 TikTok One（TTO）达人。

TCM 与 TTO Creator Marketplace 接口对比

下表概述了 TikTok Creator Marketplace（TCM）与 TTO Creator Marketplace接口之间的差异。

| 变化内容 {24%}| TCM 接口 {36%} | TTO Creator Marketplace 接口 {40%} |
|---|---|---|
| 接口路径 | /v1.3/tcm/creator/discover/ | /v1.3/tto/tcm/creator/discover/ |
| 相同请求参数 | `min_followers`<br> `max_followers`<br> `languages`<br> `min_avg_views`<br> `max_avg_views`<br> `sort_field`<br> `page`<br> `page_size` | `min_followers`<br> `max_followers`<br> `languages`<br> `min_avg_views`<br> `max_avg_views`<br> `sort_field`<br> `page`<br> `page_size` |
| 废弃请求参数 | N/A | `tcm_account_id`<br> `country_code`<br> `engagement_rate`<br> `mobile_os`<br> `creator_categories`<br> `max_campaign_count`<br> `min_campaign_count`<br> `has_responsive_badge`<br> `major_audience_country_code`<br> `major_audience_gender`<br> `major_audience_age`<br> `query` |
| 新增请求参数 | N/A | `tto_tcm_account_id`<br> `country_codes`<br> `state_provinces`<br> `content_label_ids`<br> `industry_label_ids`<br> `min_creator_price`<br> `max_creator_price`<br> `creator_price_currency`<br> `min_median_views`<br> `max_median_views`<br> `min_engagement_rate`<br> `max_engagement_rate`<br> `follower_country_codes`<br> `follower_gender_ratio`<br> `follower_age`<br> `keyword_search`<br> `sort_order` |
| 相同返回参数 | `creators`<br> `creators.handle_name`<br> `creators.display_name`<br> `creators.profile_image`<br> `creators.followers_count`<br> `creators.videos_count`<br> `creators.likes_count`<br> `page_info`<br> `page_info.page`<br> `page_info.page_size`<br> `page_info.total_number`<br> `page_info.total_page` | `creators`<br> `creators.handle_name`<br> `creators.display_name`<br> `creators.profile_image`<br> `creators.followers_count`<br> `creators.videos_count`<br> `creators.likes_count`<br> `page_info`<br> `page_info.page`<br> `page_info.page_size`<br> `page_info.total_number`<br> `page_info.total_page` |
| 废弃返回参数 |N/A |  `creators.followings_count` |
| 新增返回参数 | N/A | `creators.following_count`|

请求

地址 https://business-api.tiktok.com/open_api/v1.3/tto/tcm/creator/discover/

方法 GET

Header

|字段{32%}|类型{15%}|描述{53%}|
|---|---|---|
|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)。|

参数

|字段{32%}|类型{15%}|描述{53%}|
|---|---|---|
|tto_tcm_account_id {必填}|string|TikTok One Creator Marketplace账户的 ID。<br><br>要获取您通过访问令牌 `Access-Token` 可访问的账户 ID，使用接口 [/tto/oauth2/tcm/](1815693478150146.html)。|
|country_codes {必填}|string[]|按达人所在国家或地区代码筛选。<br><br>如果传入多个代码，这些代码应属于同一地区类别。<br><br>枚举值及每个代码的地区类别参见 `country_codes` [可选值](https://haapi.byteintl.net/gateway/document/info?openscene_id=7089534145277198337&doc_platform_id=12&doc_id=1825017307843585&language=ENGLISH#item-link-List%20of%20values%20for%20country_codes)。<br>|
|state_provinces|string[]|仅当 `country_codes` 为 `["US"]` 时生效。<br><br>按达人所在州或省份筛选。<br><br>目前仅支持美国各州。<br><br>枚举值参见 `state_provinces` 的[可选值](https://haapi.byteintl.net/gateway/document/info?openscene_id=7089534145277198337&doc_platform_id=12&doc_id=1825017307843585&language=ENGLISH#item-link-List%20of%20values%20for%20state_provinces)。|
|content_label_ids|string[]|按视频内容标签 ID 筛选。<br>视频内容标签是达人 TikTok 账号的主要内容方向，主要代表达人的原生内容方向。<br><br>最大数量：100。<br><br>要获取视频内容标签 ID 列表，可使用接口 [/tto/tcm/category/label/](1816372654109698.html)，将 label_type 设置为 SEARCH，并从返回参数 content_labels 中获取 label_id。|
|industry_label_ids|string[]|按行业标签 ID 筛选。<br>行业标签表示基于达人制作的商业内容（包括广告创意和其 TikTok 账号上的品牌内容）划分的达人所属行业，代表其在特定行业的商业经验。<br><br>最大数量：100。<br><br>要获取行业标签 ID 列表，可使用接口 [/tto/tcm/category/label/](1816372654109698.html)，将 label_type 设置为 SEARCH，并从返回参数 industry_labels 中获取 label_id。|
|min_followers|number|按最低粉丝数筛选。<br><br>默认值：0。|
|max_followers|number|按最高粉丝数筛选。<br><br>此字段没有默认值。|
|languages|string[]|按语言筛选。<br><br>枚举值参见 `languages` [可选值](https://haapi.byteintl.net/gateway/document/info?openscene_id=7089534145277198337&doc_platform_id=12&doc_id=1825017307843585&language=ENGLISH#item-link-List%20of%20values%20for%20languages)。<br><br>默认不按语言筛选。|
|min_creator_price|number|按达人最低起始价格筛选，币种由 `creator_price_currency` 指定。<br><br>默认值：0。|
|max_creator_price|number|按达人最高起始价格筛选，币种由 `creator_price_currency` 指定。<br><br>无默认值。|
|creator_price_currency|string|达人起始价格筛选条件 `min_creator_price` 和 `max_creator_price` 对应的币种。<br><br>枚举值：`USD`。<br>默认值：`USD`。|
|min_avg_views|number|按最低平均播放量筛选。<br><br>平均播放量表示达人视频的平均观看次数。<br>默认值：0。|
|max_avg_views|number|按最高平均播放量筛选。<br><br>无默认值。|
|min_median_views|number|按最低播放量中位数筛选。<br><br>播放量中位数表示达人最近视频播放量范围的中间值，按从低到高的顺序排列，展示达人内容的典型视频播放量。<br><br>默认值：0。|
|max_median_views|number|按最高播放量中位数筛选。<br><br>此字段没有默认值。|
|min_engagement_rate|float|按最小互动率筛选。<br><br>互动率表示有多少比例的观众与内容互动。具体计算方法是将评论、点赞和分享的总数除以视频播放量。<br><br>取值范围：0-1。<br>默认值：0。|
|max_engagement_rate|float|按最大互动率筛选。<br><br>取值范围：0-1。<br>无默认值。|
|follower_country_codes|string[]|按粉丝所在地的地区代码列表筛选。<br><br>枚举值参见<a href="#item-link-follower_country_codes可选值">`follower_country_codes` 可选值</a>。|
|follower_gender_ratio|string|按粉丝性别比例筛选。<br><br>枚举值：<ul><li>`FEMALE_50`：女性观众百分比超过 50%。</li><li>`FEMALE_60`：女性观众百分比超过 60%。</li><li>`FEMALE_70`：女性观众百分比超过 70%。</li><li>`MALE_50`：男性观众百分比超过 50%。</li><li>`MALE_60`：男性观众百分比超过 60%。</li><li>`MALE_70`：男性观众百分比超过 70%。</li></ul>|
|follower_age|string|按粉丝主要年龄段筛选。<br><br>枚举值：<ul><li>`18-24`: 18-24.</li><li>`25-34`: 25-34.</li><li>`35-44`: 35-44.</li><li>`45-54`: 45-54.</li><li>`55+`: 55+.</li></ul>|
|keyword_search|string|搜索达人的关键词。<br><br>长度限制：100 字符。<br><br>支持模糊匹配。|
|sort_field|string|排序指标。<br><br>枚举值：<ul><li>`RELEVANCE`：相关性。</li><li>`FOLLOWERS`：粉丝数。</li><li>`MEDIAN_VIEWS`：播放量中位数。</li><li>`ENGAGEMENT_RATE`：互动率。</li></ul>默认值：`RELEVANCE`。<br><br>可通过此字段对返回数据进行排序。|
|sort_order|string|排序顺序。<br><br>枚举值：<ul><li>`ASC`：升序。</li><li>`DESC`：降序。</li></ul>默认值：`DESC`。|
|page|number|当前页码。<br><br>取值范围：≥1。<br>默认值：1。|
|page_size|number|当前页大小。<br><br>取值范围：1-200。<br>默认值：24。|

country_codes可选值

state_provinces可选值

| 值{30%} | 描述{70%} |
|---|---|
| `Alabama` | 阿拉巴马州 |
| `Alaska` | 阿拉斯加州 |
| `Arizona` | 亚利桑那州 |
| `Arkansas` | 阿肯色州 |
| `California` | 加利福尼亚州 |
| `Colorado` | 科罗拉多州 |
| `Connecticut` | 康涅狄格州 |
| `Delaware` | 特拉华州 |
| `Florida` | 佛罗里达州 |
| `Georgia` | 佐治亚州 |
| `Hawaii` | 夏威夷州 |
| `Idaho` | 爱达荷州 |
| `Illinois` | 伊利诺伊州 |
| `Indiana` | 印第安纳州 |
| `Iowa` | 爱荷华州 |
| `Kansas` | 堪萨斯州 |
| `Kentucky` | 肯塔基州 |
| `Louisiana` | 路易斯安那州 |
| `Maine` | 缅因州 |
| `Maryland` | 马里兰州 |
| `Massachusetts` | 马萨诸塞州 |
| `Michigan` | 密歇根州 |
| `Minnesota` | 明尼苏达州 |
| `Mississippi` | 密西西比州 |
| `Missouri` | 密苏里州 |
| `Montana` | 蒙大拿州 |
| `Nebraska` | 内布拉斯加州 |
| `Nevada` | 内华达州 |
| `New Hampshire` | 新罕布什尔州 |
| `New Jersey` | 新泽西州 |
| `New Mexico` | 新墨西哥州 |
| `New York` | 纽约州 |
| `North Carolina` | 北卡罗来纳州 |
| `North Dakota` | 北达科他州 |
| `Ohio` | 俄亥俄州 |
| `Oklahoma` | 俄克拉荷马州 |
| `Oregon` | 俄勒冈州 |
| `Pennsylvania` | 宾夕法尼亚州 |
| `Rhode Island` | 罗得岛州 |
| `South Carolina` | 南卡罗来纳州 |
| `South Dakota` | 南达科他州 |
| `Tennessee` | 田纳西州 |
| `Texas` | 德克萨斯州 |
| `Utah` | 犹他州 |
| `Vermont` | 佛蒙特州 |
| `Virginia` | 弗吉尼亚州 |
| `Washington` | 华盛顿州 |
| `West Virginia` | 西弗吉尼亚州 |
| `Wisconsin` | 威斯康星州 |
| `Wyoming` | 怀俄明州 |

languages可选值

| 值{30%} | 描述{70%} |
|---|---|
| `ar` | 阿拉伯语 |
| `de` | 德语 |
| `en` | 英语 |
| `es` | 西班牙语 |
| `fr` | 法语 |
| `id` | 印度尼西亚语 |
| `it` | 意大利语 |
| `ja` | 日语 |
| `ko` | 韩语 |
| `ms` | 马来语 |
| `pt` | 葡萄牙语 |
| `th` | 泰语 |
| `tl` | 他加禄语 |
| `tr` | 土耳其语 |
| `vi` | 越南语 |

follower_country_codes可选值

| 值{30%} | 描述{70%} |
|---|---|
| `AE` | 阿拉伯联合酋长国 |
| `AU` | 澳大利亚 |
| `BR` | 巴西 |
| `CA` | 加拿大 |
| `DE` | 德国 |
| `EG` | 埃及 |
| `ES` | 西班牙 |
| `FR` | 法国 |
| `GB` | 英国 |
| `ID` | 印度尼西亚 |
| `IL` | 以色列 |
| `IT` | 意大利 |
| `JP` | 日本 |
| `KR` | 韩国 |
| `MY` | 马来西亚 |
| `PH` | 菲律宾 |
| `RU` | 俄罗斯 |
| `SA` | 沙特阿拉伯 |
| `SG` | 新加坡 |
| `TH` | 泰国 |
| `TR` | 土耳其 |
| `TW` | 中国台湾 |
| `US` | 美国 |
| `VN` | 越南 |

示例

(code curl http)
curl --location --request GET 'https://business-api.tiktok.com/open_api/v1.3/tto/tcm/creator/discover/?tto_tcm_account_id={{tto_tcm_account_id}}&country_codes=["US"]' \
--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|返回数据。|
#|creators|object[]|发现的达人。|
##|handle_name|string|达人的用户名。|
##|display_name|string|达人的显示名称。|
##|profile_image|string|达人头像的临时 URL。<br><br>URL 中包含了过期时间，位于 `x-expires` 参数之后，格式为以秒为单位的 Epoch/Unix 时间戳。<br><br>一旦该 URL 过期，你需要调用 [/tto/tcm/creator/discover/](1825017307843585.html) 接口来获取新的 URL。|
##|followers_count|number|达人的粉丝总数。|
##|following_count|number|达人在 TikTok 上关注的账号总数。|
##|likes_count|number|达人视频的总点赞数。|
##|videos_count|number|达人发布的公开视频总数。|
#|page_info|object|分页信息。|
##|page|integer|当前页码。|
##|page_size|integer|每页大小。|
##|total_number|integer|总结果数。|
##|total_page|integer|总页数。|

示例

(code Success-Response http)
HTTPS/1.1 200 OK
{
    "code": 0,
    "message": "OK",
    "request_id": "{{request_id}}",
    "data": {
        "creators": [
            {
                "display_name": "{{display_name}}",
                "followers_count": 4419006,
                "following_count": 428,
                "handle_name": "{{handle_name}}",
                "likes_count": 133618856,
                "profile_image": "{{profile_image}}",
                "videos_count": 606
            },
            {
                "display_name": "{{display_name}}",
                "followers_count": 2149447,
                "following_count": 1309,
                "handle_name": "{{handle_name}}",
                "likes_count": 89181425,
                "profile_image": "{{profile_image}}",
                "videos_count": 1047
            }
        ],
        "page_info": {
            "page": 1,
            "page_size": 24,
            "total_number": 1,
            "total_page": 2
        }
    }
}
(/code)