--- title: "达人搜索/Search Creator" method: GET path: "/api/v1/douyin/xingtu_v2/search_creator" tags: ["Douyin-Xingtu-V2-API"] --- # 达人搜索/Search Creator `GET /api/v1/douyin/xingtu_v2/search_creator` ## Request - Base URL: `https://api.tikhub.io` (the document declares no server; this is the origin it was published from) - URL: `https://api.tikhub.io/api/v1/douyin/xingtu_v2/search_creator` - Auth: HTTP bearer # [中文] ### 用途: - 搜索或筛选抖音短视频达人，支持关键词搜索、合作诉求、达人属性、效果指标、 报价区间、内容主题和观众画像等完整筛选条件。 - `keyword` 可留空；留空时仅使用其它筛选条件浏览达人。 - 价格：0.002$ / 次 ### 基础搜索参数: - `keyword`: 搜索词。`seach_type=2` 时用于匹配达人昵称；`seach_type=3` 时用于匹配 达人发布的内容。可留空，留空表示只按筛选条件查询。 - `seach_type`: 搜索方式。`2`=按昵称找人（默认），`3`=按内容找人。 - `time_range_days`: 内容搜索的时间范围，可选 `30`、`90`、`180` 天，默认 `180`； 仅在 `seach_type=3` 时生效。 - `page`: 页码，从 `1` 开始，默认 `1`；每页返回数量由接口固定。 - `sort_field`: 排序字段，默认 `score`，表示按综合匹配度排序。 - `sort_type`: 排序方向，`1`=升序，`2`=降序，默认 `2`。 ### 合作诉求参数: - `task_category`: 合作对象/任务类型，例如短视频等合作场景。不同合作对象可用的 筛选项可能不同。 - `marketing_target`: 营销目标，用于限定当前合作希望达到的营销效果。 - `first_industry_id`: 一级行业 ID，`0`=不限，用于筛选适配指定行业的达人。 - `author_list_id`: 主题推荐达人清单 ID；提供后用于查询该主题清单内的达人。 ### 达人匹配度参数: - `tag`: 达人类型 ID。多个 ID 用逗号分隔，例如 `1,6`，表示匹配任一类型。 - `persona_tags`: 达人人设、学历、认证或调性 ID。逗号分隔表示组内满足任一， 分号分组表示每组都要满足，例如 `1129,110401;110213`。 - `gender`: 达人性别，`1`=男，`2`=女；不传表示不限。 - `fans_min`: 粉丝数下限，例如 `100000` 表示至少 10 万粉丝。 - `fans_max`: 粉丝数上限，例如 `200000` 表示最多 20 万粉丝。 ### 效果与性价比参数: - `expected_play_min`: 预期播放量下限。 - `expected_play_max`: 预期播放量上限。 - `cpm_min`: 预期 CPM 下限，即每千次播放成本下限。 - `cpm_max`: 预期 CPM 上限，即每千次播放成本上限。 - `cpe_min`: 预期 CPE 下限，即单次互动成本下限。 - `cpe_max`: 预期 CPE 上限，即单次互动成本上限。 - `interact_rate_min`: 互动率下限，使用 `0-1` 小数，例如 `0.02` 表示 2%。 - `interact_rate_max`: 互动率上限，使用 `0-1` 小数。 - `play_over_rate_min`: 完播率下限，使用 `0-1` 小数。 - `play_over_rate_max`: 完播率上限，使用 `0-1` 小数。 - `burst_text_rate_min`: 爆文率下限，使用 `0-1` 小数。 - `burst_text_rate_max`: 爆文率上限，使用 `0-1` 小数。 ### 报价参数: - `price_type`: 报价时长档位，`1`=1-20 秒视频，`2`=21-60 秒视频， `3`=60 秒以上视频。该参数仅与 `price_min` / `price_max` 配合使用。 - `price_min`: 达人报价下限；提供时必须同时提供 `price_type`。 - `price_max`: 达人报价上限；提供时必须同时提供 `price_type`。 - 不传 `price_min` 和 `price_max` 时不执行报价筛选；单独传 `price_type` 也不会执行 报价筛选。 ### 扩展画像参数: - `extra_filter`: 额外筛选条件的 JSON 数组字符串，用于内容主题、观众/粉丝画像、 观众八大人群、地域和其它动态筛选项。数组中每项必须包含非空字符串 `field_name` 和 `field_value`，需要关联档位的字段还可包含 `rel_id`。 - 常用 `field_name`： - `content_theme_labels_180d`: 近 180 天内容主题，`field_value` 示例 `["生活好物评测"]`。 - `watcher_gender_female_rate_v2__ge`: 女性观众占比下限，示例 `0.6` 表示 女性观众占比不低于 60%。 - `watcher_gender_male_rate_v2__ge`: 男性观众占比下限。 - `watcher_age_most_new`: 主要观众年龄编码数组，例如 `[22]`。 - `link_crowd_profile`: 观众八大人群编码数组，例如 `[60,55,53,57]`。 - `extra_filter` 不是合法 JSON 数组、元素缺少 `field_name` / `field_value` 时返回 422。 ### 筛选值来源: - `tag`、`persona_tags` 等达人字段 ID 可通过 `/api/v1/douyin/xingtu_v2/get_author_market_fields` 获取。 - 内容主题、观众画像和八大人群等动态字段及编码可通过 `/api/v1/douyin/xingtu_v2/get_search_field_options` 获取。 ### 返回: - `authors`: 达人搜索结果列表，包含达人信息、粉丝数、报价和效果指标等。 - `pagination`: 分页信息，包含当前页、每页数量、是否还有下一页和结果总数。 - 其它统计信息以响应中的 `extra_data` 等字段为准。 # [English] ### Purpose: - Search or filter Douyin short-video creators with keyword, cooperation, creator profile, performance, price, content-theme, and audience-profile filters. - `keyword` may be empty for filter-only browsing. - Price: 0.002$ / time ### Basic search parameters: - `keyword`: Optional search term; nickname text for `seach_type=2`, content text for `seach_type=3`. Leave empty to use filters only. - `seach_type`: `2`=nickname (default), `3`=content. - `time_range_days`: Content range of `30`, `90`, or `180` days; only applies to content search. - `page`: Page number starting from 1. - `sort_field`: Sort field; default `score`. - `sort_type`: `1`=ascending, `2`=descending. ### Cooperation and match parameters: - `task_category`: Cooperation target or task category. - `marketing_target`: Marketing objective. - `first_industry_id`: First-level industry ID; `0` means unrestricted. - `author_list_id`: Featured creator-list ID. - `tag`: Creator-category IDs, comma-separated. - `persona_tags`: Persona/education/certification/style IDs. Commas mean OR within a group; semicolons separate groups that must all match. - `gender`: Creator gender, `1`=male, `2`=female. - `fans_min` / `fans_max`: Follower-count range. ### Performance and price parameters: - `expected_play_min` / `expected_play_max`: Expected-play range. - `cpm_min` / `cpm_max`: Expected cost-per-thousand-play range. - `cpe_min` / `cpe_max`: Expected cost-per-engagement range. - `interact_rate_min` / `interact_rate_max`: Interaction-rate range as 0-1 decimals. - `play_over_rate_min` / `play_over_rate_max`: Completion-rate range as 0-1 decimals. - `burst_text_rate_min` / `burst_text_rate_max`: Viral-post-rate range as 0-1 decimals. - `price_type`: Video-length price tier: `1`=1-20s, `2`=21-60s, `3`=over 60s. - `price_min` / `price_max`: Creator-price range. `price_type` is required when either bound is supplied. Omitting both bounds disables price filtering. ### Extended profile filters: - `extra_filter`: JSON-array string for content themes, audience/fan profiles, crowd segments, region, and other dynamic filters. Every item requires non-empty string `field_name` and `field_value`. - Common fields: `content_theme_labels_180d`, `watcher_gender_female_rate_v2__ge`, `watcher_gender_male_rate_v2__ge`, `watcher_age_most_new`, and `link_crowd_profile`. - Use `get_author_market_fields` for creator-field IDs and `get_search_field_options` for dynamic profile fields and codes. ### Return: - Creator results, pagination information, and related metrics. # [示例 1：按昵称搜索 / Example 1: nickname search] keyword = "飞机" seach_type = 2 # [示例 2：按内容搜索 / Example 2: content search] keyword = "飞机" seach_type = 3 time_range_days = 180 # [示例 3：纯条件筛选 / Example 3: filter-only search] keyword = "" seach_type = 3 time_range_days = 180 page = 1 sort_field = "score" sort_type = 2 task_category = 1 marketing_target = 1 first_industry_id = 0 tag = "36" gender = 2 fans_min = 100000 fans_max = 200000 extra_filter = '[{"field_name":"content_theme_labels_180d","field_value":"[\"生活好物评测\"]"},{"field_name":"watcher_gender_female_rate_v2__ge","field_value":"0.6"},{"field_name":"link_crowd_profile","field_value":"[60,55,53,57]"}]' ## Query parameters - `keyword` string: 可选搜索词；留空时仅按筛选条件浏览。seach_type=2匹配昵称，=3匹配内容/Optional keyword; empty means filter-only browsing - `seach_type` 2 | 3 - `time_range_days` 30 | 90 | 180 - `page` integer: 页码/Page number - `sort_field` string: 排序字段，默认score综合排序/Sort field, default score (comprehensive) - `sort_type` integer: 排序方式，1=升序，2=降序/Sort type, 1=asc, 2=desc - `task_category` integer: 合作对象/Cooperation target - `marketing_target` integer: 营销目标/Marketing target - `first_industry_id` integer: 适配行业ID，0=不限/Industry ID, 0=unlimited - `author_list_id` string, nullable: 主题推荐达人清单ID/Featured creator list ID - `price_type` 1 | 2 | 3 - `price_min` integer, nullable: 达人报价下限，提供时必须同时提供price_type/Minimum creator price - `price_max` integer, nullable: 达人报价上限，提供时必须同时提供price_type/Maximum creator price - `tag` string, nullable: 达人类型ID，多个用逗号分隔，如`1,6`/Creator category IDs, comma-separated - `persona_tags` string, nullable: 达人人设/学历/认证/调性ID。逗号分隔=满足任一；分号分组=每组都要满足，如`1129,110401;110213`/Persona IDs. Comma=match any, semicolon=group AND - `gender` integer, nullable: 达人性别，1=男，2=女/Creator gender, 1=male, 2=female - `fans_min` integer, nullable: 粉丝数下限/Minimum followers - `fans_max` integer, nullable: 粉丝数上限/Maximum followers - `expected_play_min` integer, nullable: 预期播放量下限/Minimum expected plays - `expected_play_max` integer, nullable: 预期播放量上限/Maximum expected plays - `cpm_min` number, nullable: 预期CPM下限/Minimum expected CPM - `cpm_max` number, nullable: 预期CPM上限/Maximum expected CPM - `cpe_min` number, nullable: 预期CPE下限/Minimum expected CPE - `cpe_max` number, nullable: 预期CPE上限/Maximum expected CPE - `interact_rate_min` number, nullable: 互动率下限，0-1小数，0.02=2%/Minimum interaction rate, 0-1 decimal - `interact_rate_max` number, nullable: 互动率上限，0-1小数/Maximum interaction rate, 0-1 decimal - `play_over_rate_min` number, nullable: 完播率下限，0-1小数/Minimum play-completion rate, 0-1 decimal - `play_over_rate_max` number, nullable: 完播率上限，0-1小数/Maximum play-completion rate, 0-1 decimal - `burst_text_rate_min` number, nullable: 爆文率下限，0-1小数/Minimum viral-post rate, 0-1 decimal - `burst_text_rate_max` number, nullable: 爆文率上限，0-1小数/Maximum viral-post rate, 0-1 decimal - `extra_filter` string, nullable: 额外画像筛选的JSON数组字符串，每项必须包含非空字符串field_name和field_value；支持内容主题、观众/粉丝画像、八大人群和地域等维度/Extra profile filters as a JSON-array string; field_name and field_value must be non-empty strings ## Response `200` Successful Response - ResponseModel - `code` integer: HTTP status code | HTTP状态码 - `request_id` string, nullable: Unique request identifier | 唯一请求标识符 - `message` string: Response message (EN-US) | 响应消息 (English) - `message_zh` string: Response message (ZH-CN) | 响应消息 (中文) - `support` string: Support message | 支持消息 - `time` string: The time the response was generated | 生成响应的时间 - `time_stamp` integer: The timestamp the response was generated | 生成响应的时间戳 - `time_zone` string: The timezone of the response time | 响应时间的时区 - `docs` string, nullable: Link to the API Swagger documentation for this endpoint | 此端点的 API Swagger 文档链接 - `cache_message` string, nullable: Cache message (EN-US) | 缓存消息 (English) - `cache_message_zh` string, nullable: Cache message (ZH-CN) | 缓存消息 (中文) - `cache_url` string, nullable: The URL to access the cached result | 访问缓存结果的 URL - `router` string: The endpoint that generated this response | 生成此响应的端点 - `params` unknown - `data` unknown ## Other responses - `422`: Validation Error ## Changes - **2026-10-08** `96a122a5f220`: 2 info - added the optional property `detail/items/ctx` to the response with the `422` status - added the optional property `detail/items/input` to the response with the `422` status - **2026-09-01** `50f9ec6e1cd3`: 1 info - endpoint added [Operation history](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/changes/api/v1/douyin/xingtu_v2/search_creator/get.md) --- [API](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi.md) - [All operations](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/llms.txt) - [OpenAPI document](https://skmtc.dev/tikhub/apis/tikhub-douyin-tiktok-xiaohongshu-lemon8-bilibili-kuaishou-pi/revisions/86a3483c705a?raw)