Creativault Creator Data Collection

Prerequisites

Set the following environment variables:

• CV_API_KEY — Creativault Open API Key (obtain from admin dashboard)
• CV_USER_IDENTITY — Operator email address
• CV_API_BASE_URL (optional) — API base URL, defaults to http://api.creativault.vip

Linux / macOS:

export CV_API_KEY=cv_live_your_key_here
export CV_USER_IDENTITY=your_email@example.com

Windows PowerShell:

$env:CV_API_KEY = "cv_live_your_key_here"
$env:CV_USER_IDENTITY = "your_email@example.com"

Capabilities

All scripts accept a JSON string as command-line argument. Results are output as JSON to stdout.

Language: Always respond to the user in the same language they use. If the user writes in Chinese, respond in Chinese. If in English, respond in English.

Choosing the Right Approach

Before executing, determine the best approach based on user intent:

Decision rules:

• If the user gives filter conditions (keyword, country, follower count) → use search first. It returns results instantly.
• If the user gives a specific creator link/username and asks for "similar"/"lookalike"/"相似达人" → use resolve + lookalike workflow.
• If the user gives specific profile links or usernames → use collection (async).
• If search results satisfy the user's needs → no need to submit a collection task.
• Only use collection when the user explicitly needs detailed/enriched data for specific creators.
• After any collection task completes, ALWAYS call export_task_data.mjs to generate a downloadable file (default xlsx) and present the download link to the user. Do NOT just call get_task_data.mjs and show raw JSON.

Service Level Selection

Users may not know what S1/S2/S3 means. The agent MUST ask the user to confirm the service level before executing a search. Never auto-select silently.

Service level reference (show to user when asking):

Rules:

• If user does NOT specify a service level → show the table above and ask: "请选择服务等级：S1（基础名单，1积分/条）、S2（精准触达，3积分/条）、S3（深度画像，4积分/条）？"
• If user explicitly says "S1"/"S2"/"S3" or "深度画像"/"精准触达"/"名单" → use as specified, no need to ask again
• If user has already chosen a level in the current conversation → reuse that level for subsequent searches unless they say otherwise
• ALWAYS show the service level and credits consumed in the stats section after search results
• After showing results, display: "本次使用 S2（精准触达）等级，消耗 60 积分，剩余配额 xxx"

Output Formatting

展示搜索或采集结果时，使用以下分区格式。字段要展示齐全，表格要对齐整齐。

TikTok 输出模板

✅ 搜索成功！找到 N 个 [国家] [平台] [关键词]达人

📊 采集结果

| #   | 用户名      | 昵称        | 粉丝数  | 获赞数   | 平均播放 | 互动率  | 国家 | 主页链接          |
| --- | ----------- | ----------- | ------- | -------- | -------- | ------- | ---- | ----------------- |
| 1   | username1   | Nickname1   | 33.1K   | 95.5万   | 1.2万    | 6.50%   | US   | [查看][link1]     |
| 2   | username2   | Nickname2   | 59.2K   | 146.0万  | 3.8万    | 3.75%   | US   | [查看][link2]     |

[link1]: https://www.tiktok.com/@username1
[link2]: https://www.tiktok.com/@username2

📈 统计信息
• 总匹配数：12,652 个达人
• 服务等级：S2（精准触达）
• 本次消耗：60 积分
• 剩余配额：992 次
• 请求ID：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

YouTube 输出模板

| #   | 用户名      | 频道名      | 订阅数  | 总观看    | 平均播放 | 互动率  | 国家 | 频道链接          |
| --- | ----------- | ----------- | ------- | --------- | -------- | ------- | ---- | ----------------- |
| 1   | username1   | Channel1    | 120K    | 5,200万   | 8.5万    | 4.20%   | US   | [查看][link1]     |

Instagram 输出模板

| #   | 用户名      | 昵称        | 粉丝数  | 帖子数   | 平均播放 | 互动率  | 国家 | 主页链接          |
| --- | ----------- | ----------- | ------- | -------- | -------- | ------- | ---- | ----------------- |
| 1   | username1   | Nickname1   | 85.3K   | 342      | 2.1万    | 5.30%   | US   | [查看][link1]     |

相似达人输出模板

🔍 找到 N 个与 @seed_username 相似的达人

📊 相似达人列表

| #   | 用户名      | 昵称        | 粉丝数  | 平均播放 | 互动率  | 相似度  | 国家 | 主页链接          |
| --- | ----------- | ----------- | ------- | -------- | ------- | ------ | ---- | ----------------- |
| 1   | username1   | Nickname1   | 120K    | 3.8万    | 7.20%   | 85.0%  | US   | [查看][link1]     |
| 2   | username2   | Nickname2   | 95.5K   | 2.1万    | 5.50%   | 78.3%  | US   | [查看][link2]     |

[link1]: https://www.tiktok.com/@username1
[link2]: https://www.tiktok.com/@username2

📈 统计信息
• 种子达人：@seed_username（平台ID：7123456789）
• 结果总数：N 个相似达人
• 本次消耗：10 积分
• 剩余配额：xxx 次
• 请求ID：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

格式规则

• 分区结构：用 emoji 标题分隔不同区域（✅ 搜索结果、📊 采集结果、📈 统计信息）
• 字段齐全：展示 API 返回的所有核心字段，不省略
• 表格对齐：每列用固定宽度对齐，分隔线用 --- 填充，确保列宽一致
• 链接处理：表格内用 [查看][linkN] 引用式链接，在表格下方定义完整 URL，避免撑坏表格
• 数字格式：
  • 粉丝/播放等数值：≥1万 用 K（如 33.1K）、≥100万 用 M（如 1.2M）；<1万 用逗号分隔（如 3,911）
  • 获赞/总观看等大数值：用万/亿简写（如 95.5万、5.2亿）
  • 互动率：转为百分比，保留两位小数（如 0.065 → 6.50%）
• 统计信息：单独列出总匹配数、服务等级、本次消耗积分、剩余配额、请求 ID，用无序列表展示
• 总匹配数展示规则：API 的 meta.total 仅在筛选条件 > 2 个时返回数值，≤ 2 个筛选条件时返回 null。当 total 为 null 时，统计信息中不展示"总匹配数"这一行，避免显示"总匹配数：null"
• 默认展示 5~10 条，超过时询问用户是否需要更多
• 展示结果后主动询问："需要导出完整数据到 CSV/Excel 吗？"

Quota Awareness

Every API response includes meta.quota_remaining and search responses include meta.credits_consumed. Monitor these values:

• credits_consumed shows how many credits were deducted for the current request (varies by service_level: S1=1/record, S2=3/record, S3=4/record)
• If quota_remaining < 50: warn the user that quota is running low
• If quota_remaining < 10: strongly recommend the user to conserve quota
• If quota_remaining = 0 or error 42902: inform the user that daily quota is exhausted (resets at UTC 00:00)
• When using S2/S3 service levels, remind the user that credits are consumed faster

Workflows

Workflow 1: Search Creators (instant)

node {baseDir}/scripts/search_creators.mjs '{"platform":"tiktok","keyword":"beauty","country_code":"US","followers_cnt_gte":10000,"size":20,"service_level":"S2"}'

Workflow 2: Search + Export (instant)

# Search and export to local CSV in one pipeline
node {baseDir}/scripts/search_creators.mjs '{"platform":"tiktok","keyword":"beauty","country_code":"US","size":50,"service_level":"S2"}' | node {baseDir}/scripts/export_to_csv.mjs '{"output":"creators.csv"}'

# Append page 2 to the same file
node {baseDir}/scripts/search_creators.mjs '{"platform":"tiktok","keyword":"beauty","country_code":"US","size":50,"page":2,"service_level":"S2"}' | node {baseDir}/scripts/export_to_csv.mjs '{"output":"creators.csv"}'

Workflow 3: Batch Collection (async, 5~30 min)

Important: Collection tasks are async and take 5~30 minutes. You MUST poll for completion before fetching data.

Step 1 — Submit task:

node {baseDir}/scripts/submit_collection_task.mjs '{"task_type":"LINK_BATCH","platform":"tiktok","values":["https://www.tiktok.com/@creator1","https://www.tiktok.com/@creator2"],"task_name":"Q1 collection"}'

Step 2 — Poll until completed (auto-polls every 60s):

node {baseDir}/scripts/poll_task_status.mjs '{"task_id":"task_xxx"}'

After submitting, inform the user: "Collection task submitted. This typically takes 5~30 minutes. I'll monitor the progress for you."

Step 3 — After task is completed, ALWAYS export the data as a file first, then show the download link to the user. Only use get_task_data.mjs if the user explicitly asks for raw JSON data.

# PREFERRED: Export as file and give user the download link
node {baseDir}/scripts/export_task_data.mjs '{"task_id":"task_xxx","format":"xlsx"}'

# Only if user explicitly requests raw JSON:
node {baseDir}/scripts/get_task_data.mjs '{"task_id":"task_xxx","page":1,"size":50}'

Rule: When a collection task completes, the default action is to call export_task_data.mjs with format:"xlsx" and present the file_url download link to the user. Do NOT just call get_task_data.mjs and dump raw JSON — users want a downloadable file.

Workflow 4: Keyword Collection (async)

# Step 1: Submit
node {baseDir}/scripts/submit_keyword_task.mjs '{"platform":"tiktok","keywords":["beauty tips","skincare routine"]}'

# Step 2: Poll
node {baseDir}/scripts/poll_task_status.mjs '{"task_id":"task_xxx"}'

# Step 3: ALWAYS export as file after completion
node {baseDir}/scripts/export_task_data.mjs '{"task_id":"task_xxx","format":"xlsx"}'

Workflow 5: Find Similar/Lookalike Creators (instant)

When the user provides a creator profile link or username and asks for similar creators:

Step 1 — Extract username from the link (e.g., https://www.tiktok.com/@creator_demo → creator_demo), then resolve to platform ID:

node {baseDir}/scripts/resolve_creator.mjs '{"platform":"tiktok","username":"creator_demo"}'

This returns platform_id (e.g., 7123456789012345678).

Step 2 — Use the platform_id to find lookalike creators:

node {baseDir}/scripts/find_lookalike.mjs '{"seed_platform_id":"7123456789012345678","seed_platform":"tiktok","target_platform":"tiktok","limit":10}'

Optional filters: target_region, target_language, follower_min, follower_max, avg_views_min, avg_views_max, female_rate_min.

Cross-platform search: Set target_platform different from seed_platform to find similar creators on another platform (e.g., find YouTube creators similar to a TikTok creator).

Decision rules for lookalike:

• If user gives a profile URL → extract username, call resolve first, then lookalike
• If user gives a username → call resolve first, then lookalike
• If user already has a platform_id → skip resolve, call lookalike directly
• If resolve returns error 40401 (creator not found) → inform user the creator is not in the database

Script Parameters

search_creators.mjs

platform is required. All other parameters are optional filters.

Service Level Details

Platform-specific parameters: see Platform Parameters Reference.

submit_collection_task.mjs

submit_keyword_task.mjs

poll_task_status.mjs

get_task_status.mjs

get_task_data.mjs

export_task_data.mjs

Exports task data to file (server-side), uploads to OSS, returns download URL. Repeated calls with same task_id + format return cached file.

export_to_csv.mjs

Pipe JSON from search or collection results to export as local CSV file. Supports incremental append.

get_download_url.mjs

resolve_creator.mjs

Resolve a creator username to their platform unique ID. Required before calling find_lookalike.mjs.

Returns: platform_id, username, display_name, avatar_url, followers_count.

find_lookalike.mjs

Find similar/lookalike creators based on a seed creator. Supports cross-platform search.

Returns: items array with uid, username, nickname, avatar_url, profile_url, country_code, followers_count, avg_views, engagement_rate, match_score.

Error Handling

References

• API Reference — Full request/response field documentation
• Platform Parameters — TikTok/YouTube/Instagram specific filters
• Industry Categories — Industry category tree with Chinese/English mapping (for industry_category_levels_list and industry params)
• Country Codes — ISO country codes with Chinese/English names and region shortcuts
• Language Codes — ISO language codes with Chinese/English names
• Error Codes — Complete error code list and troubleshooting

Changelog

v1.2.0

• Added similar/lookalike creator discovery via resolve_creator.mjs + find_lookalike.mjs
• Search API now defaults to S2 (precise reach) service level
• meta.total only returned when filter conditions > 2; output formatting hides total when null
• Added cross-platform lookalike search support
• Added Workflow 5 for lookalike creator discovery

v1.1.0

• Added server-side export (xlsx/csv/html) via export_task_data.mjs
• Added auto-retry on 429 rate limit in API client
• Added quota awareness guidance
• Added output formatting guidance for agents
• Added smart workflow selection (search vs collection)
• Unified all script logs and SKILL.md to English

v1.0.0

• Initial release: search, collection, polling, local CSV export