OpenAPI

自然语言搜索达人

POST/v1/creators/nl-search

认证方式: X-API-Key
所需 scope: creator:nl:search
计费: 价格以账户生效规则为准
限流: 查看当前限流规则

请求参数

该请求使用 JSON 请求体提交。

querystring必填

自然语言达人搜索需求；传 seed 时可为空

platformstring可选

达人平台，支持 instagram/ins/ig、tiktok/tt/tk、youtube/ytb/yt

默认值: "instagram"

modestring可选

召回模式，默认 hybrid；TikTok/YouTube 请求 hybrid 或 vector 时自动按 scalar 执行

默认值: "hybrid"

hybrid · vector · scalar

route_schemastring可选

Instagram 向量及向量表全文召回拓扑：four_route=profile/topic/style/commercial；two_route=profile/business。默认 four_route

默认值: "four_route"

four_route · two_route

split_semantic_queryboolean可选

是否按向量 route 拆分 semantic query；默认 true，使用四路或二路 route-specific query 并批量向量化；false 使用 shared query

默认值: true

expand_brand_keywordsboolean可选

已废弃的兼容参数；服务端忽略该值，将在后续版本移除

默认值: false

scalar_modestring可选

标量召回后端：dual 使用 Instagram 向量表双全文列；legacy 使用现有标量链路；campaign_hashtag 使用 Campaign 纯 hashtag 召回链路（仅 TT/YTB，有 seed 或无 hashtag 时自动 fallback）。TikTok/YouTube 请求 dual 时按 legacy 执行

默认值: "dual"

dual · legacy · campaign_hashtag

enable_max_candidates_rowboolean可选

是否为 Campaign hashtag 同步召回启用匹配视频候选行上限；默认关闭，仅 TikTok/YouTube 实际执行 campaign_hashtag 时生效

默认值: false

limitinteger可选

返回达人数量

默认值: 20

1 ≤ limit ≤ 200

route_top_kinteger可选

每路语义召回 TopK。实际执行会保证不低于 limit 对应下限：limit < 100 时为 200，否则为 2 * limit

默认值: 200

10 ≤ route_top_k ≤ 1000

route_concurrencyinteger可选

单请求内语义召回 route 最大并发数，默认 4 路并发

默认值: 4

1 ≤ route_concurrency ≤ 4

rrf_knumber可选

RRF 融合平滑系数

默认值: 90

1 ≤ rrf_k ≤ 1000

debugboolean可选

是否返回 V2 调试信息

默认值: false

service_levelstring可选

服务等级

默认值: "S1"

seed_creatorsarray可选

种子达人；显式传入时默认按整体相似参与所有向量路

展开字段

platformstring可选

urlstring可选

namestring可选

uidstring可选

constraintarray可选

展开字段

该接口暂不提供 Schema 详情。

hard_filterobject可选

显式硬过滤条件；与 query 冲突时以本对象为准

展开字段

followers_cntobject可选

Inclusive numeric hard-filter range.

展开字段

minnumber可选

0 ≤ min ≤ ∞

maxnumber可选

0 ≤ max ≤ ∞

last10_avg_video_views_cntobject可选

Inclusive numeric hard-filter range.

展开字段

minnumber可选

0 ≤ min ≤ ∞

maxnumber可选

0 ≤ max ≤ ∞

last10_avg_video_interaction_rateobject可选

Inclusive ratio hard-filter range.

展开字段

minnumber可选

0 ≤ min ≤ 1

maxnumber可选

0 ≤ max ≤ 1

influencer_price_usdobject可选

Inclusive numeric hard-filter range.

展开字段

minnumber可选

0 ≤ min ≤ ∞

maxnumber可选

0 ≤ max ≤ ∞

aud_female_pctobject可选

Inclusive ratio hard-filter range.

展开字段

minnumber可选

0 ≤ min ≤ 1

maxnumber可选

0 ≤ max ≤ 1

aud_countryobject可选

Audience values whose combined share must exceed a threshold.

展开字段

valuesarray必填

展开字段

该接口暂不提供 Schema 详情。

min_sharenumber可选

所选受众值的合计占比下限；不传则沿用当前默认阈值

0 ≤ min_share ≤ 1

aud_languageobject可选

Audience values whose combined share must exceed a threshold.

展开字段

valuesarray必填

展开字段

该接口暂不提供 Schema 详情。

min_sharenumber可选

所选受众值的合计占比下限；不传则沿用当前默认阈值

0 ≤ min_share ≤ 1

aud_ageobject可选

Audience values whose combined share must exceed a threshold.

展开字段

valuesarray必填

展开字段

该接口暂不提供 Schema 详情。

min_sharenumber可选

所选受众值的合计占比下限；不传则沿用当前默认阈值

0 ≤ min_share ≤ 1

creator_countryarray可选

展开字段

该接口暂不提供 Schema 详情。

creator_genderstring可选

Male · Female

creator_languagearray可选

展开字段

该接口暂不提供 Schema 详情。

creator_agearray可选

展开字段

该接口暂不提供 Schema 详情。

is_real_personboolean可选

has_emailboolean可选

last_video_publish_dateinteger可选

1 ≤ last_video_publish_date ≤ ∞

exclude_uidsarray可选

检索阶段排除的达人 UID 集合；会下推至各召回后端

展开字段

该接口暂不提供 Schema 详情。

响应

successboolean必填

dataobject可选

Natural-language creator search response.

展开字段

itemsarray必填

展开字段

uidstring必填

达人唯一标识

usernamestring可选

用户名

nicknamestring可选

昵称

avatar_urlstring可选

头像链接

profile_urlstring可选

主页链接

country_codestring可选

国家/地区代码

followers_countinteger可选

粉丝数

avg_viewsinteger可选

近 10 条视频平均播放量

engagement_ratenumber可选

近 10 条视频平均互动率

match_scorenumber可选

NL 检索匹配分；vector 保持现有向量分算法；hybrid 使用 RRF Top1 命中分支的归一化加权相似分标定 RRF 分数；标量无可靠分时为空

totalinteger必填

debugobject可选

Stable, non-redundant V2 debug contract.

展开字段

schema_versionstring可选

默认值: "2"

executionobject必填

Requested and actual retrieval paths.

展开字段

platformstring必填

instagram · tiktok · youtube

requestedstring必填

hybrid · vector · scalar

actualstring必填

hybrid · vector · scalar

requested_scalar_modestring可选

dual · legacy · campaign_hashtag

effective_scalar_modestring可选

dual · legacy · campaign_hashtag

scalar_mode_fallbackobject可选

Why execution differs from the requested mode.

展开字段

codestring必填

messagestring必填

fallbackobject可选

Why execution differs from the requested mode.

展开字段

codestring必填

messagestring必填

total_msnumber可选

queryobject必填

Request-level parsing facts shared by retrieval branches.

展开字段

originalstring可选

parse_msobject可选

filtersobject可选

seedsobject可选

Seed inputs and resolution results.

展开字段

requestedarray可选

resolvedarray可选

skipped_constraintsobject可选

lexical_termsarray可选

retrievalobject必填

Retrieval branches and the shared vector schema.

展开字段

schemastring可选

four_route · two_route

duration_msnumber可选

vectorobject可选

Vector recall without lexical or parser-only details.

展开字段

statusstring必填

queryobject必填

Semantic query shape used by vector recall.

metricstring必填

gate_modestring可选

overfetch_factornumber可选

concurrencyinteger可选

requested_depthinteger可选

candidatesinteger可选

embedding_msnumber可选

duration_msnumber可选

fusion_msnumber可选

routesobject可选

errorobject可选

A retrieval branch failure.

scalarobject可选

fusionobject可选

Cross-branch fusion facts only.

展开字段

algorithmstring可选

默认值: "rrf"

knumber必填

weightsobject必填

union_candidatesinteger可选

duration_msnumber可选

enrichmentobject可选

Deferred result-field enrichment.

展开字段

enabledboolean必填

countinteger可选

duration_msnumber可选

results_explanationarray可选

展开字段

rankinteger必填

uidstring必填

profile_urlstring必填

vector_routesobject可选

fulltext_routesobject可选

branchesobject可选

rrf_scorenumber可选

match_scorenumber可选

errorobject可选

错误详情

展开字段

codeinteger必填

业务错误码

messagestring必填

可读错误信息

metaobject可选

响应元数据

展开字段

request_idstring可选

请求唯一标识

默认值: ""

pageinteger可选

当前页码

sizeinteger可选

每页数量

totalinteger可选

总数

quota_remaininginteger可选

剩余配额（-1 表示不限制）

默认值: -1

service_levelstring可选

本次请求的服务等级

langstring可选

响应语言（cn/en），为空表示未翻译

platformstring可选

本次请求的达人平台

recall_typestring可选

召回类型：hybrid / vector / scalar

credits_consumedinteger可选

本次请求扣减的积分数

默认值: 0

credits_remaininginteger可选

积分余额（-1 不限制）

默认值: -1

billable_unitsinteger可选

Server-calculated billable units for this response

默认值: 0

0 ≤ billable_units ≤ ∞

skill_namestring可选

调用方 skill 名称

skill_current_versionstring可选

调用方 skill 当前版本

skill_latest_versionstring可选

服务端声明的最新 skill 版本

skill_min_supported_versionstring可选

服务端声明的最低支持版本

skill_update_availableboolean可选

是否存在可用 skill 更新

默认值: false

skill_update_requiredboolean可选

是否要求更新 skill 后再继续使用

默认值: false

skill_update_messagestring可选

skill 更新提示文案

skill_update_manifest_urlstring可选

skill 更新 manifest URL

请求示例

curl -X POST 'http://api.creativault.vip/openapi/v1/creators/nl-search' \
  -H 'Content-Type: application/json' \
  -H "X-API-Key: $CV_API_KEY" \
  --data '{
  "query": "example",
  "platform": "instagram",
  "mode": "hybrid",
  "route_schema": "four_route",
  "split_semantic_query": true,
  "expand_brand_keywords": false,
  "scalar_mode": "dual",
  "enable_max_candidates_row": false,
  "limit": 20,
  "route_top_k": 200,
  "route_concurrency": 4,
  "rrf_k": 90,
  "debug": false,
  "service_level": "S1"
}'

此示例根据响应 Schema 自动生成。

响应示例

{
  "success": true,
  "data": {
    "items": [
      {
        "uid": "example",
        "username": null,
        "nickname": null,
        "avatar_url": null,
        "profile_url": null,
        "country_code": null,
        "followers_count": null,
        "avg_views": null,
        "engagement_rate": null,
        "match_score": null
      }
    ],
    "total": 1,
    "debug": {
      "schema_version": "2",
      "execution": {
        "platform": null,
        "requested": null,
        "actual": null,
        "requested_scalar_mode": null,
        "effective_scalar_mode": null,
        "scalar_mode_fallback": null,
        "fallback": null,
        "total_ms": null
      },
      "query": {
        "original": null,
        "parse_ms": null,
        "filters": null,
        "seeds": null
      },
      "retrieval": {
        "schema": null,
        "duration_ms": null,
        "vector": null,
        "scalar": null
      },
      "fusion": null,
      "enrichment": null,
      "results_explanation": null
    }
  },
  "error": null,
  "meta": {
    "request_id": "",
    "page": 1,
    "size": 1,
    "total": 1,
    "quota_remaining": -1,
    "service_level": "example",
    "lang": "example",
    "platform": "example",
    "recall_type": "example",
    "credits_consumed": 0,
    "credits_remaining": -1,
    "billable_units": 0,
    "skill_name": "example",
    "skill_current_version": "example",
    "skill_latest_version": "example",
    "skill_min_supported_version": "example",
    "skill_update_available": false,
    "skill_update_required": false,
    "skill_update_message": "example",
    "skill_update_manifest_url": "example"
  }
}

查看错误处理 →