开发者平台 · API 文档

这里提供对外 API 的集成说明与示例，包括 SalesEngine 线索发现、SalesBot 自动回复与 Auto-DM 批量私信能力。

快速开始 · 概览

OutreachSkill 开发者平台提供三组核心 API：SalesEngine（智能线索发现）、SalesBot（自动化回复触达）和 Auto-DM（批量私信）。所有接口均通过开发者 API Key 进行鉴权，Key 可在 API Keys 控制台中生成。

快速开始 · Credits 消耗价格表

所有 API 调用均按 Credits 计费，与 volumn.ai 积分体系完全等价。在 Credits 充值页面购买套餐，Credits 永久有效，不过期。

API 操作	接口	消耗 Credits	说明
SalesEngine 线索发现	`POST /api/v1/sales/jobs`	80 / 次	每次搜索返回最多 500 个潜在客户，异步执行
SalesBot 发送 DM	`POST /api/sales-engine/salesbot/run`	0.4 / 条	每向一位用户发送一条私信
ViralPost 推荐	`GET /api/public/viralpost/recommendations`	1 / 次	每次拉取爆款推文推荐列表

套餐参考： Hobby $40 = 500 Credits（6 次 SalesEngine）· Pro $200 = 2,000 Credits（25 次）· Team $2,000 = 20,000 Credits（250 次）

快速开始 · 鉴权与 Key

请通过 Developer 控制台生成 API Key，格式为 vp_...。服务端调用推荐使用 x-api-key header 传入；也可使用标准 Bearer Token 方式。

# 方式一：x-api-key header（推荐）
x-api-key: vp_YOUR_KEY_HERE

# 方式二：Authorization Bearer
Authorization: Bearer vp_YOUR_KEY_HERE

生成 Key：/api-keys

快速开始 · 调用示例

以下示例展示如何调用 SalesEngine 线索发现接口：

curl -X POST "https://YOUR_DOMAIN/api/sales-engine/leads" \
  -H "x-api-key: vp_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "我们是一家 AI 写作工具 SaaS，帮助独立开发者和内容创作者提升写作效率",
    "limit": 20,
    "language": "zh"
  }'

SalesEngine API

SalesEngine · 概览

SalesEngine 是 OutreachSkill 的核心引擎，通过语义分析将产品/服务描述转化为精准的潜在客户列表。它综合利用向量相似度搜索、推文行为分析和 AI 意图评分，从 X (Twitter) 生态中发现高意向潜在客户。

POST /api/sales-engine/leads

核心线索发现（最常用）

GET /api/sales-engine/audience

分析推文受众的购买意向

GET /api/sales-engine/viral-posts

获取当前爆款帖子

GET /api/sales-engine/recommended-accounts

推荐高质量关注账号

GET /api/sales-engine/history

查看历史线索发现记录

SalesEngine · 线索发现

POST/api/sales-engine/leads

核心接口。输入产品/服务描述，返回经过 AI 意图评分的潜在客户账号列表，包含 leadIntent（high/medium/low/none）、leadScore、leadSummary 等字段。

请求体参数（JSON）

参数	类型	必填	说明
text	string	是	产品/服务描述，或包含推文 URL 的文本
limit	number	否	返回账号数量上限（1–500，默认 40）
tweetId	string	否	种子推文 ID，用于受众导向的线索发现
tweetUrl	string	否	种子推文 URL（与 tweetId 二选一）
language	string	否	输出语言："zh" \| "en"（默认自动检测）

示例

curl -X POST "https://YOUR_DOMAIN/api/sales-engine/leads" \
  -H "x-api-key: vp_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "AI-powered SaaS tool for indie developers to automate social media growth",
    "limit": 30,
    "language": "en"
  }'

响应示例（部分）

{
  "ok": true,
  "requestId": "uuid-...",
  "accounts": [
    {
      "id": "123456",
      "username": "indie_dev_jane",
      "name": "Jane Dev",
      "followersCount": 12400,
      "leadIntent": "high",
      "leadScore": 0.87,
      "leadSummary": "Active indie hacker, frequently discusses SaaS tools and automation"
    }
  ],
  "analysis": {
    "customerProfile": "Indie developer building SaaS products",
    "keywords": ["indie hacker", "SaaS", "automation", "developer tools"]
  }
}

SalesEngine · 受众分析

GET/api/sales-engine/audience

分析指定推文的受众群体，返回受众画像、购买意向分布和关键词标签。

查询参数

参数	类型	必填	说明
tweetUrl	string	是	要分析的推文 URL
limit	number	否	返回受众账号数量上限（1–200，默认 50）

SalesEngine · 爆款帖子

GET/api/sales-engine/viral-posts

获取当前 X 平台上与你的产品/服务相关的爆款帖子，按互动量排序。

查询参数

参数	类型	必填	说明
bio	string	否	产品/Persona 描述，用于个性化推荐
limit	number	否	返回帖子数量上限（1–50，默认 20）

SalesEngine · 推荐账号

GET/api/sales-engine/recommended-accounts

推荐与你产品定位高度相关的优质 X 账号，支持个性化模式和多维度过滤。

查询参数

参数	类型	必填	说明
limit	number	否	返回账号数量上限（1–100，默认 20）
language	string	否	语言过滤："en" \| "zh" \| "ja"
niche_tags	string	否	逗号分隔的细分标签，如 "AI/Tech,Startup"
bio	string	否	产品/Persona 描述，启用个性化模式
topics	string	否	逗号分隔的主题关键词，启用个性化模式
min_quality	number	否	最低质量分数（0–1，默认 0）
similarity_weight	number	否	语义相似度权重（默认 0.6）
quality_weight	number	否	质量分数权重（默认 0.4）

示例（个性化模式）

curl "https://YOUR_DOMAIN/api/sales-engine/recommended-accounts?bio=AI+writing+tool+for+developers&topics=AI,SaaS,developer+tools&limit=20" \
  -H "x-api-key: vp_YOUR_KEY_HERE"

SalesEngine · 历史记录

GET/api/sales-engine/history

返回当前用户的 SalesEngine 查询历史，包含每次运行的输入文本、分析结果和发现的线索账号。

查询参数

参数	类型	必填	说明
limit	number	否	返回记录数量上限（1–100，默认 20）
offset	number	否	分页偏移量（默认 0）

SalesBot API

SalesBot · 概览

SalesBot 负责自动化回复触达：根据 SalesEngine 发现的潜在客户，自动生成并发送个性化回复，实现从「发现线索」到「建立联系」的闭环。

GET /api/sales-engine/salesbot/overview

查看 SalesBot 统计概览

GET /api/sales-engine/salesbot/tasks

列出所有回复任务

POST /api/sales-engine/salesbot/tasks

创建新的回复任务

POST /api/sales-engine/salesbot/run

触发批量回复执行

POST /api/sales-engine/salesbot/dm/draft

生成个性化 DM 草稿

SalesBot · 任务管理

GET/api/sales-engine/salesbot/tasks

列出所有 SalesBot 回复任务及其状态。

POST/api/sales-engine/salesbot/tasks

创建新的回复任务，指定目标账号列表和回复模板。

GET 查询参数

参数	类型	必填	说明
limit	number	否	返回任务数量上限（1–100，默认 20）
offset	number	否	分页偏移量（默认 0）
status	string	否	状态过滤："scheduled" \| "running" \| "completed" \| "failed"

POST 请求体参数

参数	类型	必填	说明
name	string	是	任务名称
accountId	string	是	用于发送回复的 X 账号 ID
targets	string[]	是	目标 X 用户名数组
message	string	是	回复消息模板
scheduleAt	string	否	ISO 8601 计划执行时间（默认立即执行）

SalesBot · 触发执行

POST/api/sales-engine/salesbot/run

触发 SalesBot 批量执行：处理待发送的回复任务队列，向目标账号发送回复。

请求体参数

参数	类型	必填	说明
taskId	string	否	指定运行特定任务 ID（默认自动选择）
limit	number	否	本批次最多发送回复数（1–20，默认 3）

示例

curl -X POST "https://YOUR_DOMAIN/api/sales-engine/salesbot/run" \
  -H "x-api-key: vp_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"limit": 5}'

SalesBot · DM 草稿生成

POST/api/sales-engine/salesbot/dm/draft

为指定目标账号生成个性化 DM 草稿，基于其公开资料和你的产品描述进行 AI 定制。

请求体参数

参数	类型	必填	说明
targetUsername	string	是	目标 X 用户名（不含 @）
text	string	是	产品/服务描述，用于个性化生成
tone	string	否	消息语气："professional" \| "casual" \| "friendly"（默认 "professional"）
language	string	否	输出语言："zh" \| "en"（默认自动检测）

示例

curl -X POST "https://YOUR_DOMAIN/api/sales-engine/salesbot/dm/draft" \
  -H "x-api-key: vp_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "targetUsername": "indie_dev_jane",
    "text": "AI writing tool that helps developers 10x their content output",
    "tone": "friendly",
    "language": "en"
  }'

Auto-DM API

Auto-DM · 概览

Auto-DM 支持批量私信触达：向目标用户列表发送个性化 DM，支持定时发送、进度追踪和发送日志。适合配合 SalesEngine 线索发现结果，实现从「发现」到「私信」的全自动化流程。

Auto-DM · 任务管理

GET/api/sales-engine/auto-dm/tasks

列出所有 Auto-DM 任务及其发送状态。

POST/api/sales-engine/auto-dm/tasks

创建新的 Auto-DM 任务，指定发送账号、消息内容和收件人列表。

POST 请求体参数

参数	类型	必填	说明
name	string	是	任务名称
senderAccountId	string	是	用于发送 DM 的 X 账号 ID
message	string	是	DM 消息内容
recipients	object[]	是	收件人数组，每项包含 { participantId, username }
scheduleAt	string	否	ISO 8601 计划发送时间（默认立即发送）

示例

curl -X POST "https://YOUR_DOMAIN/api/sales-engine/auto-dm/tasks" \
  -H "x-api-key: vp_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Outreach Campaign",
    "senderAccountId": "my_x_account_id",
    "message": "Hi {{username}}, I noticed you work on indie SaaS projects...",
    "recipients": [
      { "participantId": "123456789", "username": "indie_dev_jane" },
      { "participantId": "987654321", "username": "saas_founder_bob" }
    ]
  }'

Auto-DM · 搜索目标用户

GET/api/sales-engine/auto-dm/search-users

通过关键词搜索 X 用户，用于构建 Auto-DM 收件人列表。

查询参数

参数	类型	必填	说明
q	string	是	搜索关键词（用户名、主题或话题）
limit	number	否	返回结果数量上限（1–50，默认 20）

示例

curl "https://YOUR_DOMAIN/api/sales-engine/auto-dm/search-users?q=indie+hacker+SaaS&limit=30" \
  -H "x-api-key: vp_YOUR_KEY_HERE"

ViralPost API

ViralPost API · 推荐爆款推文

GET/api/public/viralpost/recommendations

为指定的 X 用户名推荐近期爆款推文卡片（返回 tweetUrl / 内容 / 发布时间 / 分数）。

查询参数

参数	类型	必填	说明
username	string	是	X 用户名（不含 @）
period	string	否	时间范围："today" \| "week"（默认 "week"）
limit	number	否	返回推文数量（1–30，默认 10）

示例

curl "https://YOUR_DOMAIN/api/public/viralpost/recommendations?username=elonmusk&period=week&limit=5" \
  -H "x-api-key: vp_YOUR_KEY_HERE"

ViralPost API · 错误码

400	请求参数错误（缺少必填字段或格式不正确）
401	未授权：缺少或无效的 API Key
429	请求频率超限，请稍后重试
500	服务端内部错误，可携带 requestId 联系支持
502	内部服务通信失败，通常为临时性错误

ViralPost API · 限流与重试

当返回 429 时建议使用指数退避策略重试（例如 0.5s → 1s → 2s → 4s）。

建议为每次请求生成唯一 requestId 并记录日志，便于问题排查。

SalesEngine 线索发现接口（/api/sales-engine/leads）超时时间为 300 秒，建议客户端相应设置超时。