OpenAPI

creators nl search

POST/v1/creators/nl-search

Authentication: X-API-Key
Required scope: creator:nl:search
Billing: Pricing follows your active account rules
Rate limits: View your active rate limits

Parameters

Send this request as a JSON body.

querystringRequired

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

platformstringOptional

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

Default: "instagram"

modestringOptional

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

Default: "hybrid"

hybrid · vector · scalar

route_schemastringOptional

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

Default: "four_route"

four_route · two_route

split_semantic_querybooleanOptional

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

Default: true

expand_brand_keywordsbooleanOptional

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

Default: false

scalar_modestringOptional

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

Default: "dual"

dual · legacy · campaign_hashtag

enable_max_candidates_rowbooleanOptional

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

Default: false

limitintegerOptional

返回达人数量

Default: 20

1 ≤ limit ≤ 200

route_top_kintegerOptional

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

Default: 200

10 ≤ route_top_k ≤ 1000

route_concurrencyintegerOptional

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

Default: 4

1 ≤ route_concurrency ≤ 4

rrf_knumberOptional

RRF 融合平滑系数

Default: 90

1 ≤ rrf_k ≤ 1000

debugbooleanOptional

是否返回 V2 调试信息

Default: false

service_levelstringOptional

服务等级

Default: "S1"

seed_creatorsarrayOptional

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

Show fields

platformstringOptional

urlstringOptional

namestringOptional

uidstringOptional

constraintarrayOptional

Show fields

Schema details are unavailable for this endpoint.

hard_filterobjectOptional

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

Show fields

followers_cntobjectOptional

Inclusive numeric hard-filter range.

Show fields

minnumberOptional

0 ≤ min ≤ ∞

maxnumberOptional

0 ≤ max ≤ ∞

last10_avg_video_views_cntobjectOptional

Inclusive numeric hard-filter range.

Show fields

minnumberOptional

0 ≤ min ≤ ∞

maxnumberOptional

0 ≤ max ≤ ∞

last10_avg_video_interaction_rateobjectOptional

Inclusive ratio hard-filter range.

Show fields

minnumberOptional

0 ≤ min ≤ 1

maxnumberOptional

0 ≤ max ≤ 1

influencer_price_usdobjectOptional

Inclusive numeric hard-filter range.

Show fields

minnumberOptional

0 ≤ min ≤ ∞

maxnumberOptional

0 ≤ max ≤ ∞

aud_female_pctobjectOptional

Inclusive ratio hard-filter range.

Show fields

minnumberOptional

0 ≤ min ≤ 1

maxnumberOptional

0 ≤ max ≤ 1

aud_countryobjectOptional

Audience values whose combined share must exceed a threshold.

Show fields

valuesarrayRequired

Show fields

Schema details are unavailable for this endpoint.

min_sharenumberOptional

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

0 ≤ min_share ≤ 1

aud_languageobjectOptional

Audience values whose combined share must exceed a threshold.

Show fields

valuesarrayRequired

Show fields

Schema details are unavailable for this endpoint.

min_sharenumberOptional

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

0 ≤ min_share ≤ 1

aud_ageobjectOptional

Audience values whose combined share must exceed a threshold.

Show fields

valuesarrayRequired

Show fields

Schema details are unavailable for this endpoint.

min_sharenumberOptional

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

0 ≤ min_share ≤ 1

creator_countryarrayOptional

Show fields

Schema details are unavailable for this endpoint.

creator_genderstringOptional

Male · Female

creator_languagearrayOptional

Show fields

Schema details are unavailable for this endpoint.

creator_agearrayOptional

Show fields

Schema details are unavailable for this endpoint.

is_real_personbooleanOptional

has_emailbooleanOptional

last_video_publish_dateintegerOptional

1 ≤ last_video_publish_date ≤ ∞

exclude_uidsarrayOptional

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

Show fields

Schema details are unavailable for this endpoint.

Response

successbooleanRequired

dataobjectOptional

Natural-language creator search response.

Show fields

itemsarrayRequired

Show fields

uidstringRequired

达人唯一标识

usernamestringOptional

用户名

nicknamestringOptional

昵称

avatar_urlstringOptional

头像链接

profile_urlstringOptional

主页链接

country_codestringOptional

国家/地区代码

followers_countintegerOptional

粉丝数

avg_viewsintegerOptional

近 10 条视频平均播放量

engagement_ratenumberOptional

近 10 条视频平均互动率

match_scorenumberOptional

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

totalintegerRequired

debugobjectOptional

Stable, non-redundant V2 debug contract.

Show fields

schema_versionstringOptional

Default: "2"

executionobjectRequired

Requested and actual retrieval paths.

Show fields

platformstringRequired

instagram · tiktok · youtube

requestedstringRequired

hybrid · vector · scalar

actualstringRequired

hybrid · vector · scalar

requested_scalar_modestringOptional

dual · legacy · campaign_hashtag

effective_scalar_modestringOptional

dual · legacy · campaign_hashtag

scalar_mode_fallbackobjectOptional

Why execution differs from the requested mode.

Show fields

codestringRequired

messagestringRequired

fallbackobjectOptional

Why execution differs from the requested mode.

Show fields

codestringRequired

messagestringRequired

total_msnumberOptional

queryobjectRequired

Request-level parsing facts shared by retrieval branches.

Show fields

originalstringOptional

parse_msobjectOptional

filtersobjectOptional

seedsobjectOptional

Seed inputs and resolution results.

Show fields

requestedarrayOptional

resolvedarrayOptional

skipped_constraintsobjectOptional

lexical_termsarrayOptional

retrievalobjectRequired

Retrieval branches and the shared vector schema.

Show fields

schemastringOptional

four_route · two_route

duration_msnumberOptional

vectorobjectOptional

Vector recall without lexical or parser-only details.

Show fields

statusstringRequired

queryobjectRequired

Semantic query shape used by vector recall.

metricstringRequired

gate_modestringOptional

overfetch_factornumberOptional

concurrencyintegerOptional

requested_depthintegerOptional

candidatesintegerOptional

embedding_msnumberOptional

duration_msnumberOptional

fusion_msnumberOptional

routesobjectOptional

errorobjectOptional

A retrieval branch failure.

scalarobjectOptional

fusionobjectOptional

Cross-branch fusion facts only.

Show fields

algorithmstringOptional

Default: "rrf"

knumberRequired

weightsobjectRequired

union_candidatesintegerOptional

duration_msnumberOptional

enrichmentobjectOptional

Deferred result-field enrichment.

Show fields

enabledbooleanRequired

countintegerOptional

duration_msnumberOptional

results_explanationarrayOptional

Show fields

rankintegerRequired

uidstringRequired

profile_urlstringRequired

vector_routesobjectOptional

fulltext_routesobjectOptional

branchesobjectOptional

rrf_scorenumberOptional

match_scorenumberOptional

errorobjectOptional

错误详情

Show fields

codeintegerRequired

业务错误码

messagestringRequired

可读错误信息

metaobjectOptional

响应元数据

Show fields

request_idstringOptional

请求唯一标识

Default: ""

pageintegerOptional

当前页码

sizeintegerOptional

每页数量

totalintegerOptional

总数

quota_remainingintegerOptional

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

Default: -1

service_levelstringOptional

本次请求的服务等级

langstringOptional

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

platformstringOptional

本次请求的达人平台

recall_typestringOptional

召回类型：hybrid / vector / scalar

credits_consumedintegerOptional

本次请求扣减的积分数

Default: 0

credits_remainingintegerOptional

积分余额（-1 不限制）

Default: -1

billable_unitsintegerOptional

Server-calculated billable units for this response

Default: 0

0 ≤ billable_units ≤ ∞

skill_namestringOptional

调用方 skill 名称

skill_current_versionstringOptional

调用方 skill 当前版本

skill_latest_versionstringOptional

服务端声明的最新 skill 版本

skill_min_supported_versionstringOptional

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

skill_update_availablebooleanOptional

是否存在可用 skill 更新

Default: false

skill_update_requiredbooleanOptional

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

Default: false

skill_update_messagestringOptional

skill 更新提示文案

skill_update_manifest_urlstringOptional

skill 更新 manifest URL

Request example

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

This example is generated from the response schema.

Response example

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

View error handling →