手册目录

KOLens REST API — 面向开发者的达人营销 API

最近更新: 2026-06-10

一句话总结

KOLens API 用标准 REST + Bearer 令牌开放完整达人工作流：提交 TikTok、Instagram、X、抖音的关键词抓取（返回 202 + 任务 id，每 10 条结果 1 积分）、轮询任务、用丰富过滤条件（互动率、国家、品类、有无邮箱）查询达人数据库，并以编程方式驱动名单、监控、预警、视频追踪和 CRM。基础地址 https://kolens.ai，密钥在应用内 API 密钥页创建，抓取提交限频 5 次/分钟，积分不足返回 HTTP 402。若你构建的是 AI 智能体而非自定义代码，MCP 服务通常是更优路径。

认证

在网页端「账户 → API 密钥」创建密钥。所有 /api/* 请求以 Bearer 令牌携带。密钥与你的账号绑定用于计费——只放在服务端，绝不要写进客户端代码。

export KOLENS_API_KEY="kol_xxxxxxxxxxxx"
curl https://kolens.ai/api/kols \
  -H "Authorization: Bearer $KOLENS_API_KEY"

核心流程：搜索 → 轮询 → 查询

1. 提交关键词抓取

TikTok（50 条视频 = 5 积分，预扣）

curl -X POST https://kolens.ai/api/scrape \
  -H "Authorization: Bearer $KOLENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "skincare routine", "max_videos": 50, "region": "US"}'
# → 202 {"job_id": "…", "status": "queued", …}

其余平台格式一致：POST /api/instagram/scrape {"hashtag": "kbeauty", "max_videos": 50} · POST /api/x/scrape {"keyword": "ai tools", "max_tweets": 50} · POST /api/douyin/scrape {"keyword": "美妆", "max_videos": 50}。全部返回 202 与任务 id；计费均为 max(1, ceil(结果数 ÷ 10)) 积分，失败退还。

2. 轮询任务

curl https://kolens.ai/api/jobs/$JOB_ID \
  -H "Authorization: Bearer $KOLENS_API_KEY"
# → {"status": "completed", "kol_count": 12, "total_videos": 50, …}
# Excel download:
#   GET /api/jobs/$JOB_ID/export

状态依次为 queued → running → completed（或 failed）。建议带退避地轮询（间隔几秒足够）；GET /api/jobs 列出近期任务。

3. 查询达人数据库

curl "https://kolens.ai/api/kols?keyword=skincare%20routine\
&require_email=true&min_engagement_rate=0.04\
&min_followers=10000&sort_by=avg_views" \
  -H "Authorization: Bearer $KOLENS_API_KEY"

主要过滤条件：platform、min/max_followers、min_engagement_rate（小数——0.04 即 4%）、min_avg_views、country（两位国家码）、category、require_email、require_website、hide_sellers、verified_only、scope=personal|team|both、sort_by。加 llm_friendly=true 可为每行附带预消化的 summary、risk_flags 与 next_actions——专为投喂 LLM 设计。单个达人：GET /api/kols/{username}；受众：GET /api/kols/{username}/audience。

端点族

功能族	端点
发现	POST /api/scrape · /api/instagram/scrape · /api/x/scrape · /api/douyin/scrape · /api/kols/profile-scrape
任务	GET /api/jobs · /api/jobs/{id} · /api/jobs/{id}/export
数据库	GET /api/kols · /api/kols/{username} · /api/kols/{username}/audience · /snapshots · /videos
名单	POST/GET/PATCH/DELETE /api/lists · GET/POST /api/lists/{id}/members · PATCH …/members/{username} · POST /api/lists/{id}/assign-export
监控与预警	GET/POST /api/watchlist · DELETE /api/watchlist/{username} · GET /api/alerts · POST /api/alerts/{id}/read · GET/PUT /api/alert-preferences
视频追踪	POST /api/videos/track · GET /api/videos/tracked · GET /api/videos/{id}/tracking · GET /api/videos/compare
CRM	GET/POST/PATCH /api/crm/conversations · POST …/{id}/ai/draft · …/ai/summarise · POST /api/crm/tasks
计划与用量	POST/GET/PATCH/DELETE /api/discovery-plans · GET /api/usage/daily · /jobs · /ledger

限制与错误

限频：每密钥每分钟 5 次抓取提交；读取无单独限频（轮询请保持礼貌间隔）。
401 — 密钥缺失/无效 · 402 — 积分不足（任务未启动）· 404 — 资源不存在 · 422 — 参数校验失败（带字段说明）。
完整的 OpenAPI（Swagger）交互文档随 API 服务提供，含全部字段定义——本页覆盖稳定核心。

说明

在 Claude 或其他 AI 智能体上构建？MCP 服务用 OAuth 和工具模式封装了同一套 API——通常比裸 REST 更省代码。见「MCP 接入」。

常见问题

有沙箱或免费开发额度吗？

针对已有数据的读取全部免费，大部分集成开发零成本。需要真实抓取的端到端测试，$0.99 试用包（5 积分）足够跑完整一轮搜索。

如何等待任务完成？

对 GET /api/jobs/{id} 每隔几秒带退避地轮询；通常 2–5 分钟完成。任务对象包含 stage 和 progress，可用于展示实时状态。

互动率是小数还是百分比？

API 全程使用小数：0.04 即 4%。min_engagement_rate 过滤条件遵循同一约定。

多个应用能共用一个密钥吗？

建议每个集成单独建一个密钥——密钥带标签、可单独吊销，用量报表也能按系统归因消耗。

认证