开始使用

Revor AI API v2 提供潜在客户发现、公开网页与联系人搜索、海关贸易数据、Connect 账号查询和单次外联。耗时操作采用异步任务，客户端提交后使用统一任务接口查询结果。

发起第一个请求

准备好 API Key 后，可以先查询积分余额，确认鉴权和账户状态正常：

cURL复制
curl "https://revor.ai/api/v2/credits" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME"

选择能力

潜在客户发现能力在当前 API 路径和响应字段中使用 websets / webset。它表示一份持续生成并可分页读取的潜客名单，不要求调用方理解任何内部实现。

Base URL

https://revor.ai/api/v2

API v1 的 Connect 和 Outreach 接口暂时保留兼容。两个版本可以使用同一套 API Key，但新接入应使用 v2 路径，并确保 Key 具有对应接口权限。

鉴权

推荐使用 Authorization: Bearer header：

cURL复制
curl "https://revor.ai/api/v2/credits" \
  -H "Authorization: Bearer sk-revor-REPLACE_ME"

也可以使用 x-api-key：

cURL复制
curl "https://revor.ai/api/v2/credits" \
  -H "x-api-key: sk-revor-REPLACE_ME"

不要把 API Key 放在 URL、前端代码、公开仓库或日志中。

会员限流与并发

开放 API 与 MCP 共用账户级额度。多个 API Key 和两种调用协议不会分别获得一套额度。

请求按普通读取、任务轮询、数据任务创建和外联操作分别限制。Credits、每分钟请求频率和活动任务并发是三套独立约束。各套餐额度、响应头、错误示例和客户端重试方式参见限流、并发与重试。

通用返回结构

成功响应包含 ok: true 和 request_id。列表通常返回 items，单个资源和异步任务通常返回 item。

JSON复制
{
  "ok": true,
  "request_id": "req_xxx",
  "item": {}
}

错误响应包含稳定的公开错误码。联系支持或排查问题时请保留 request_id。

JSON复制
{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "invalid_request",
    "request_id": "req_xxx"
  }
}

幂等键

Idempotency-Key 是可选的可靠重试能力。普通请求可以不发送；如果调用方可能在网络超时后自动重试，建议为同一次业务操作生成一个唯一值：

Http复制
Idempotency-Key: 2d1ed06a-4e63-4e36-9e88-53784bb61b0b

• 同一路径、同一 Key、相同请求体：返回第一次请求的结果，不重复创建任务。
• 同一路径、同一 Key、不同请求体：返回 409。
• 一次新的真实操作应生成新的幂等键；网络超时重试应复用原键。
• 不发送 Key：每次 POST 都视为独立操作；相同请求被重复提交时会创建多个任务，并可能分别执行和计费。

例外：POST /websets/{id}/find-more 必须提供 Idempotency-Key，缺少时返回 400 idempotency_key_required。

异步任务与 Prefer wait

研究和海关接口通常返回 HTTP 202 Accepted。保存 item.id，然后轮询：

Http复制
GET /api/v2/jobs/{id}

如果调用方愿意短暂等待，可以在创建请求中加入：

Http复制
Prefer: wait=20

任务在等待时间内结束时，创建接口返回 HTTP 200 和终态任务；否则仍返回 HTTP 202。超时不代表任务失败，继续使用任务 ID 轮询即可。

Job 状态与业务资源状态

Job 和潜客名单是两层不同状态：

Text复制
POST /websets
  ├─ preparation_job：queued → running → succeeded
  └─ 潜客名单：generating_criteria → searching → verifying → completed

Job 表示某个异步操作是否执行完成；潜客名单状态表示目标发现业务本身进行到哪个阶段。因此 preparation_job.status=succeeded 只说明名单已成功启动，不代表名单已经生成完成。

接口列表

详细文档：

• 积分余额
• 限流、并发与重试
• 查询 Connect 账号
• 发送单次外联
• 自动查找并点赞 LinkedIn 相关帖子
• 异步任务
• 潜在客户发现
• 创建潜客名单
• 查询潜客名单
• 查询名单详情
• 查询挖掘条件与搜索策略
• 分页读取潜客结果
• 实时订阅潜客结果
• 扩展更多潜客
• 实时订阅 Find More
• 公开网页与企业联系人搜索
• 海关贸易数据

国家代码格式

不同能力使用的国家代码长度不同。research.public-web 的 user_location 使用 ISO 3166-1 alpha-2 两位代码，例如 US；所有海关国家过滤字段使用 ISO 3166-1 alpha-3 三位代码，例如 USA、CHN、RUS。两种格式不能混用；长度错误的代码无法表达预期过滤条件。

推荐流程

单次外联

1. GET /connect/accounts?can_send=true 取得可发送账号的 account_id。
2. 调用 POST /outreach/dispatches 或 LinkedIn 点赞接口；需要安全重试时可发送 Idempotency-Key。
3. 保存响应中的 item.id，轮询 GET /jobs/{id}。
4. 状态为 succeeded 时读取 item.result；状态为 failed 时读取 item.error.code。

潜在客户发现

1. GET /credits 确认可用积分。
2. POST /websets 创建潜客名单，保存响应中的 webset.id。
3. 使用 GET /websets/{id}/items?detail=compact&limit=10 获取快照和 checkpoint。
4. 连接 GET /websets/{id}/items/stream，实时应用结果和状态变化，直到收到 complete。

preparation_job.id 只用于确认名单是否成功启动，不代表潜在客户发现已经完成。

信息检索和海关任务

1. 提交创建请求；需要安全重试时可发送 Idempotency-Key。
2. 读取响应中的 item.id。
3. 如果 item.status 不是终态，轮询 GET /jobs/{id}。
4. 当状态为 succeeded 时读取 item.result 和 item.billing。

常见错误