DeveloperDocs.api

自然语言搜索达人

POST/v1/creators/nl-search

DeveloperDocs.authentication: X-API-Key
DeveloperDocs.permission: creator:nl:search
DeveloperDocs.billing: DeveloperDocs.configuredBilling
DeveloperDocs.limits: DeveloperDocs.configuredLimits

DeveloperDocs.parameters

DeveloperDocs.jsonBody

querystringDeveloperDocs.required

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

platformstringDeveloperDocs.optional

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

DeveloperDocs.defaultValue: "instagram"

modestringDeveloperDocs.optional

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

DeveloperDocs.defaultValue: "hybrid"

hybrid · vector · scalar

route_schemastringDeveloperDocs.optional

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

DeveloperDocs.defaultValue: "four_route"

four_route · two_route

split_semantic_querybooleanDeveloperDocs.optional

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

DeveloperDocs.defaultValue: true

expand_brand_keywordsbooleanDeveloperDocs.optional

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

DeveloperDocs.defaultValue: false

scalar_modestringDeveloperDocs.optional

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

DeveloperDocs.defaultValue: "dual"

dual · legacy · campaign_hashtag

enable_max_candidates_rowbooleanDeveloperDocs.optional

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

DeveloperDocs.defaultValue: false

limitintegerDeveloperDocs.optional

返回达人数量

DeveloperDocs.defaultValue: 20

1 ≤ limit ≤ 200

route_top_kintegerDeveloperDocs.optional

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

DeveloperDocs.defaultValue: 200

10 ≤ route_top_k ≤ 1000

route_concurrencyintegerDeveloperDocs.optional

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

DeveloperDocs.defaultValue: 4

1 ≤ route_concurrency ≤ 4

rrf_knumberDeveloperDocs.optional

RRF 融合平滑系数

DeveloperDocs.defaultValue: 90

1 ≤ rrf_k ≤ 1000

debugbooleanDeveloperDocs.optional

是否返回 V2 调试信息

DeveloperDocs.defaultValue: false

service_levelstringDeveloperDocs.optional

服务等级

DeveloperDocs.defaultValue: "S1"

seed_creatorsarrayDeveloperDocs.optional

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

DeveloperDocs.showFields

platformstringDeveloperDocs.optional

urlstringDeveloperDocs.optional

namestringDeveloperDocs.optional

uidstringDeveloperDocs.optional

constraintarrayDeveloperDocs.optional

DeveloperDocs.showFields

DeveloperDocs.schemaUnavailable

hard_filterobjectDeveloperDocs.optional

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

DeveloperDocs.showFields

followers_cntobjectDeveloperDocs.optional

Inclusive numeric hard-filter range.

DeveloperDocs.showFields

minnumberDeveloperDocs.optional

0 ≤ min ≤ ∞

maxnumberDeveloperDocs.optional

0 ≤ max ≤ ∞

last10_avg_video_views_cntobjectDeveloperDocs.optional

Inclusive numeric hard-filter range.

DeveloperDocs.showFields

minnumberDeveloperDocs.optional

0 ≤ min ≤ ∞

maxnumberDeveloperDocs.optional

0 ≤ max ≤ ∞

last10_avg_video_interaction_rateobjectDeveloperDocs.optional

Inclusive ratio hard-filter range.

DeveloperDocs.showFields

minnumberDeveloperDocs.optional

0 ≤ min ≤ 1

maxnumberDeveloperDocs.optional

0 ≤ max ≤ 1

influencer_price_usdobjectDeveloperDocs.optional

Inclusive numeric hard-filter range.

DeveloperDocs.showFields

minnumberDeveloperDocs.optional

0 ≤ min ≤ ∞

maxnumberDeveloperDocs.optional

0 ≤ max ≤ ∞

aud_female_pctobjectDeveloperDocs.optional

Inclusive ratio hard-filter range.

DeveloperDocs.showFields

minnumberDeveloperDocs.optional

0 ≤ min ≤ 1

maxnumberDeveloperDocs.optional

0 ≤ max ≤ 1

aud_countryobjectDeveloperDocs.optional

Audience values whose combined share must exceed a threshold.

DeveloperDocs.showFields

valuesarrayDeveloperDocs.required

DeveloperDocs.showFields

DeveloperDocs.schemaUnavailable

min_sharenumberDeveloperDocs.optional

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

0 ≤ min_share ≤ 1

aud_languageobjectDeveloperDocs.optional

Audience values whose combined share must exceed a threshold.

DeveloperDocs.showFields

valuesarrayDeveloperDocs.required

DeveloperDocs.showFields

DeveloperDocs.schemaUnavailable

min_sharenumberDeveloperDocs.optional

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

0 ≤ min_share ≤ 1

aud_ageobjectDeveloperDocs.optional

Audience values whose combined share must exceed a threshold.

DeveloperDocs.showFields

valuesarrayDeveloperDocs.required

DeveloperDocs.showFields

DeveloperDocs.schemaUnavailable

min_sharenumberDeveloperDocs.optional

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

0 ≤ min_share ≤ 1

creator_countryarrayDeveloperDocs.optional

DeveloperDocs.showFields

DeveloperDocs.schemaUnavailable

creator_genderstringDeveloperDocs.optional

Male · Female

creator_languagearrayDeveloperDocs.optional

DeveloperDocs.showFields

DeveloperDocs.schemaUnavailable

creator_agearrayDeveloperDocs.optional

DeveloperDocs.showFields

DeveloperDocs.schemaUnavailable

is_real_personbooleanDeveloperDocs.optional

has_emailbooleanDeveloperDocs.optional

last_video_publish_dateintegerDeveloperDocs.optional

1 ≤ last_video_publish_date ≤ ∞

exclude_uidsarrayDeveloperDocs.optional

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

DeveloperDocs.showFields

DeveloperDocs.schemaUnavailable

DeveloperDocs.response

successbooleanDeveloperDocs.required

dataobjectDeveloperDocs.optional

Natural-language creator search response.

DeveloperDocs.showFields

itemsarrayDeveloperDocs.required

DeveloperDocs.showFields

uidstringDeveloperDocs.required

达人唯一标识

usernamestringDeveloperDocs.optional

用户名

nicknamestringDeveloperDocs.optional

昵称

avatar_urlstringDeveloperDocs.optional

头像链接

profile_urlstringDeveloperDocs.optional

主页链接

country_codestringDeveloperDocs.optional

国家/地区代码

followers_countintegerDeveloperDocs.optional

粉丝数

avg_viewsintegerDeveloperDocs.optional

近 10 条视频平均播放量

engagement_ratenumberDeveloperDocs.optional

近 10 条视频平均互动率

match_scorenumberDeveloperDocs.optional

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

totalintegerDeveloperDocs.required

debugobjectDeveloperDocs.optional

Stable, non-redundant V2 debug contract.

DeveloperDocs.showFields

schema_versionstringDeveloperDocs.optional

DeveloperDocs.defaultValue: "2"

executionobjectDeveloperDocs.required

Requested and actual retrieval paths.

DeveloperDocs.showFields

platformstringDeveloperDocs.required

instagram · tiktok · youtube

requestedstringDeveloperDocs.required

hybrid · vector · scalar

actualstringDeveloperDocs.required

hybrid · vector · scalar

requested_scalar_modestringDeveloperDocs.optional

dual · legacy · campaign_hashtag

effective_scalar_modestringDeveloperDocs.optional

dual · legacy · campaign_hashtag

scalar_mode_fallbackobjectDeveloperDocs.optional

Why execution differs from the requested mode.

DeveloperDocs.showFields

codestringDeveloperDocs.required

messagestringDeveloperDocs.required

fallbackobjectDeveloperDocs.optional

Why execution differs from the requested mode.

DeveloperDocs.showFields

codestringDeveloperDocs.required

messagestringDeveloperDocs.required

total_msnumberDeveloperDocs.optional

queryobjectDeveloperDocs.required

Request-level parsing facts shared by retrieval branches.

DeveloperDocs.showFields

originalstringDeveloperDocs.optional

parse_msobjectDeveloperDocs.optional

filtersobjectDeveloperDocs.optional

seedsobjectDeveloperDocs.optional

Seed inputs and resolution results.

DeveloperDocs.showFields

requestedarrayDeveloperDocs.optional

resolvedarrayDeveloperDocs.optional

skipped_constraintsobjectDeveloperDocs.optional

lexical_termsarrayDeveloperDocs.optional

retrievalobjectDeveloperDocs.required

Retrieval branches and the shared vector schema.

DeveloperDocs.showFields

schemastringDeveloperDocs.optional

four_route · two_route

duration_msnumberDeveloperDocs.optional

vectorobjectDeveloperDocs.optional

Vector recall without lexical or parser-only details.

DeveloperDocs.showFields

statusstringDeveloperDocs.required

queryobjectDeveloperDocs.required

Semantic query shape used by vector recall.

metricstringDeveloperDocs.required

gate_modestringDeveloperDocs.optional

overfetch_factornumberDeveloperDocs.optional

concurrencyintegerDeveloperDocs.optional

requested_depthintegerDeveloperDocs.optional

candidatesintegerDeveloperDocs.optional

embedding_msnumberDeveloperDocs.optional

duration_msnumberDeveloperDocs.optional

fusion_msnumberDeveloperDocs.optional

routesobjectDeveloperDocs.optional

errorobjectDeveloperDocs.optional

A retrieval branch failure.

scalarobjectDeveloperDocs.optional

fusionobjectDeveloperDocs.optional

Cross-branch fusion facts only.

DeveloperDocs.showFields

algorithmstringDeveloperDocs.optional

DeveloperDocs.defaultValue: "rrf"

knumberDeveloperDocs.required

weightsobjectDeveloperDocs.required

union_candidatesintegerDeveloperDocs.optional

duration_msnumberDeveloperDocs.optional

enrichmentobjectDeveloperDocs.optional

Deferred result-field enrichment.

DeveloperDocs.showFields

enabledbooleanDeveloperDocs.required

countintegerDeveloperDocs.optional

duration_msnumberDeveloperDocs.optional

results_explanationarrayDeveloperDocs.optional

DeveloperDocs.showFields

rankintegerDeveloperDocs.required

uidstringDeveloperDocs.required

profile_urlstringDeveloperDocs.required

vector_routesobjectDeveloperDocs.optional

fulltext_routesobjectDeveloperDocs.optional

branchesobjectDeveloperDocs.optional

rrf_scorenumberDeveloperDocs.optional

match_scorenumberDeveloperDocs.optional

errorobjectDeveloperDocs.optional

错误详情

DeveloperDocs.showFields

codeintegerDeveloperDocs.required

业务错误码

messagestringDeveloperDocs.required

可读错误信息

metaobjectDeveloperDocs.optional

响应元数据

DeveloperDocs.showFields

request_idstringDeveloperDocs.optional

请求唯一标识

DeveloperDocs.defaultValue: ""

pageintegerDeveloperDocs.optional

当前页码

sizeintegerDeveloperDocs.optional

每页数量

totalintegerDeveloperDocs.optional

总数

quota_remainingintegerDeveloperDocs.optional

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

DeveloperDocs.defaultValue: -1

service_levelstringDeveloperDocs.optional

本次请求的服务等级

langstringDeveloperDocs.optional

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

platformstringDeveloperDocs.optional

本次请求的达人平台

recall_typestringDeveloperDocs.optional

召回类型：hybrid / vector / scalar

credits_consumedintegerDeveloperDocs.optional

本次请求扣减的积分数

DeveloperDocs.defaultValue: 0

credits_remainingintegerDeveloperDocs.optional

积分余额（-1 不限制）

DeveloperDocs.defaultValue: -1

billable_unitsintegerDeveloperDocs.optional

Server-calculated billable units for this response

DeveloperDocs.defaultValue: 0

0 ≤ billable_units ≤ ∞

skill_namestringDeveloperDocs.optional

调用方 skill 名称

skill_current_versionstringDeveloperDocs.optional

调用方 skill 当前版本

skill_latest_versionstringDeveloperDocs.optional

服务端声明的最新 skill 版本

skill_min_supported_versionstringDeveloperDocs.optional

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

skill_update_availablebooleanDeveloperDocs.optional

是否存在可用 skill 更新

DeveloperDocs.defaultValue: false

skill_update_requiredbooleanDeveloperDocs.optional

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

DeveloperDocs.defaultValue: false

skill_update_messagestringDeveloperDocs.optional

skill 更新提示文案

skill_update_manifest_urlstringDeveloperDocs.optional

skill 更新 manifest URL

DeveloperDocs.requestExample

curl -X POST 'https://openapi.creativault.ai/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"
}'

DeveloperDocs.schemaExampleNotice

DeveloperDocs.responseExample

{
  "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"
  }
}

DeveloperDocs.errorHelp →