身份验证
使用 API Key 调用接口，在请求中添加以下 HTTP 请求头。
Authorization: Bearer <YOUR_KEY>API 接入需要付费 Workspace；接口按实际使用计费。
POST/api/openapi/v1/creators/ai-searchAI 搜索
Instagram / YouTube / TikTok0.5 积分 / 位达人
Twitter / X2 积分 / 位达人
按请求人数预扣，按实际返回人数计费；失败退款。 仅 TikTok 支持 filters.videoCartOnly=true，默认关闭；开启后每位返回达人加 1 积分（当前共 1.5 积分/位）。仅匹配已有带货证据的达人，不保证实时商品状态。
支持平台Instagram / YouTube / TikTok / Twitter / X
快速调用示例 (cURL)
curl -X POST 'https://app.hicreator.ai/api/openapi/v1/creators/ai-search' \
-H 'Authorization: Bearer <YOUR_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"platform": "instagram",
"query": "分享简单健康食谱的家庭烹饪博主",
"limit": 40,
"filters": {
"regions": [
"US",
"GB"
],
"excludedRegions": [
"DE"
],
"languages": [
"en"
],
"minFollowers": 50000,
"maxFollowers": 500000,
"minPlayCount": 10000,
"playCountMetric": "median",
"creatorTypes": [
"solo_creator"
],
"faceVisibilities": [
"clear_face",
"partial_face"
],
"workspaceDeduplicationEnabled": true
}
}'请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| filters.videoCartOnly | boolean | 否 | 仅 TikTok 支持 filters.videoCartOnly=true，默认关闭；开启后每位返回达人加 1 积分（当前共 1.5 积分/位）。仅匹配已有带货证据的达人，不保证实时商品状态。查看可选值tiktok |
| platform | string | 是 | 达人所属平台。查看可选值instagram / youtube / tiktok / twitter |
| query | string | 是 | 描述你要找的达人。 |
| limit | integer | 否 | 返回人数，默认 40，最多 100。 |
| filters | object | 否 | 筛选条件。 |
| filters.regions | string[] | 否 | 包含的国家或地区，如 US、GB。 |
| filters.excludedRegions | string[] | 否 | 排除的国家或地区。 |
| filters.languages | string[] | 否 | 内容语言；中文用 zh-Hans 或 zh-Hant。查看可选值en / es / pt / fr / de / ko / ja / ar / ru / it / zh-Hant / tr / id / hi / pl / vi / th / nl / fa / zh-Hans / bn / da / uk / ro / sv / el / ms / cs / he / hu / mr / fi / sr / hr / ml / no / ta / tl / zh |
| filters.minFollowers / maxFollowers | integer | 否 | 粉丝数范围。 |
| filters.minPlayCount / maxPlayCount | integer | 否 | 播放量范围。 仅视频平台。 |
| filters.playCountMetric | string | 否 | average（平均值，默认）或 median（中位数）。 仅视频平台。 |
| filters.genders | string[] | 否 | 性别。查看可选值female / male |
| filters.ethnicities | string[] | 否 | 族裔。查看可选值white / black / asian / hispanic_latino / middle_eastern / indigenous / pacific_islander / multiracial |
| filters.creatorTypes | string[] | 否 | 达人类型。 仅视频平台。查看可选值solo_creator / couple / family / group / product_only / brand_account / media_publisher / organization / content_aggregator / virtual_creator |
| filters.faceVisibilities | string[] | 否 | 出镜情况。 仅视频平台。查看可选值clear_face / partial_face / no_face / mixed |
| filters.twitter | object | 否 | Twitter / X 筛选条件。 |
| filters.twitter.accountTypes | string[] | 否 | 账号类型。查看可选值person / brand / company / media / organization / community / aggregator / bot / unknown |
| filters.twitter.ageRanges | string[] | 否 | 年龄段。查看可选值0_17 / 18_24 / 25_34 / 35_44 / 45_54 / 55_64 / 65_plus / unknown / not_applicable |
| filters.twitter.minViewCount / maxViewCount | integer | 否 | 帖文浏览量范围。 |
| filters.twitter.viewCountMetric | string | 否 | average（平均值，默认）或 median（中位数）。 |
| filters.twitter.minFollowingCount / maxFollowingCount | integer | 否 | 关注数范围。 |
| filters.twitter.originalPublishedWithinDays | integer | 否 | 近多少天发布过原创内容（1–30 天）。 |
| filters.twitter.activeWithinDays | integer | 否 | 近多少天活跃过（1–365 天）。 |
| filters.twitter.capturedWithinDays | integer | 否 | 近多少天更新过资料（1–365 天）。 |
| filters.workspaceDeduplicationEnabled | boolean | 否 | 开启后排除历史搜索结果；排除名单始终生效。 |
响应字段
| 参数名 | 类型 | 始终返回 | 说明 |
|---|---|---|---|
| requestId | string | 是 | 请求 ID，用于排查问题。 |
| billingRequestId | string | 是 | 计费记录 ID。 |
| data | object | 是 | 查询结果。 |
| data.items | object[] | 是 | 达人列表。 |
| data.count | integer | 是 | 实际返回人数。 |
| data.items[].id | string | 是 | 平台内达人 ID。 |
| data.items[].username | string | 是 | 账号名。 |
| data.items[].fullName | string | null | 是 | 显示名称。 |
| data.items[].platform | string | 是 | 所属平台。 |
| data.items[].biography | string | null | 是 | 个人简介。 |
| data.items[].followerCount | integer | null | 是 | 粉丝或订阅者数量。 |
| data.items[].region | string | null | 是 | 所在地区。 |
| data.items[].language | string | null | 是 | 主要内容语言。 |
| data.items[].email | string | null | 是 | 公开联系邮箱。 |
| data.items[].averagePlayCount | number | null | 是 | 平均播放量。 |
| data.items[].medianPlayCount | number | null | 是 | 中位数播放量。 |
| data.items[].averageEngagementRate | number | null | 是 | 平均互动率（小数比例）。 |
| data.items[].medianEngagementRate | number | null | 是 | 中位数互动率（小数比例）。 |
| data.items[].gender | string | null | 是 | 性别。 |
| data.items[].ageRange | string | null | 是 | 年龄段。 |
| data.items[].ethnicity | string | null | 是 | 族裔。 |
| data.items[].faceVisibility | string | null | 是 | 出镜情况。 |
| data.items[].accountPositioning | string[] | 是 | 账号定位标签。 |
| data.items[].aiDescription | string | null | 是 | AI 达人简介。 |
| data.items[].profileUrl | string | 是 | 达人主页链接。 |
| data.items[].score | number | 是 | 匹配评分，越高越相关。 |
响应示例 (JSON)
{
"requestId": "<request-id>",
"billingRequestId": "<billing-request-id>",
"data": {
"items": [
{
"id": "<creator-id>",
"username": "example_creator",
"fullName": "<creator-name>",
"platform": "instagram",
"biography": "<creator-biography>",
"followerCount": 50000,
"region": "US",
"language": "en",
"email": "[email protected]",
"averagePlayCount": 12000,
"medianPlayCount": 9800,
"averageEngagementRate": 0.045,
"medianEngagementRate": 0.041,
"gender": "female",
"ageRange": "25-34",
"ethnicity": "asian",
"faceVisibility": "clear_face",
"accountPositioning": [
"<account-positioning>"
],
"aiDescription": "<ai-description>",
"profileUrl": "https://www.instagram.com/example_creator/",
"score": 0.82
}
],
"count": 1
}
}错误与重试
查看 error.message；排查时提供 requestId。结果不确定时请勿自动重试。
查看错误码
请求：400 参数无效（10001）或数量低于最低值（70004）；401 Key 无效（20001）；403 API 仅向付费 Workspace 开放（60006）；413 请求过大（10005）；415 格式不支持（10006）；429 请求过于频繁（10007）。
执行：404 Twitter 账号不存在或无法公开访问（60008）；422 搜索意图无效（60001）或目标账号无效（60002）；422 邮箱查找未完成（60009）：达到查找上限，全额退款，不代表无邮箱，请勿自动重试；502 邮箱查询失败（60003）或执行失败（60004）；504 请求超时（60005）。网关错误页转换为 API_UPSTREAM_ERROR JSON；不要自动重试付费请求。
积分：402 余额不足（70001）或超过每日限额（70006）；409 当前功能不可用（70002）或积分记录冲突（70003）。API 错误包含 error.code、error.message 和 error.requestId；业务错误在扣费开始后包含 error.billingRequestId，网关兜底可能缺少此字段，也不能据此确认退款状态。