AI求职AI招聘API探索

DEVELOPER GUIDE

开发指南

面向 ATS、校招系统、招聘外包平台和企业内部 HR 工具，开放简历解析、人岗匹配、批量筛选与 JD 优化四类接口。 企业预充值扣费，Bearer Key 鉴权，请求幂等，全程用量审计。

概览

当前共 5 个端点，覆盖招聘链路的关键 AI 节点：

  • POST /api/open/v1/resumes/parse — 简历解析为结构化文本，按页计费
  • POST /api/open/v1/matches/resume-jd — JD 与简历匹配评分，按次计费
  • POST /api/open/v1/jds/optimize — JD 优化，按模型 token 计费
  • POST /api/open/v1/batches/screen — 批量筛选（异步），按候选人数量计费
  • GET /api/open/v1/batches/:id — 查询批量任务进度与排序结果

基础地址 https://api2.bysjob.com；1 元 = 1 积分，100 point_cents = 1 积分。

API 参考全部端点的方法、参数、请求响应示例查看 →

首期不开放自助开通

企业需先绑定招聘者账号与企业资料，由后台发放 API Client 与 API Key。

快速开始

企业开通后，后台创建 API Client 并发放 hecn_live_ 开头的 API Key。明文只在创建时展示一次，服务端只存 SHA-256 哈希。

curl · 第一次请求
curl -X POST https://api2.bysjob.com/api/open/v1/matches/resume-jd \
  -H "Authorization: Bearer hecn_live_xxx" \
  -H "Idempotency-Key: quickstart-001" \
  -H "Content-Type: application/json" \
  -d '{
    "resume_text": "张三，5 年前端，精通 React/TypeScript",
    "jd_text": "招聘高级前端工程师，要求 React、TypeScript、性能优化"
  }'

Key 丢失只能重新发放

明文 Key 不会再次显示。遗失请到后台吊销旧 Key 并创建新 Key，旧 Key 立即失效。

鉴权

每个请求在 Authorization 头携带 Bearer 前缀的 API Key，与网站登录态完全分离：

http
Authorization: Bearer hecn_live_xxxxxxxxxxxxxxxxxxxx
参数类型必填说明
Authorizationstring是Bearer hecn_live_… 形式的 API Key。缺失或无效返回 401 unauthorized。
Idempotency-Keystring否幂等键，最长 160 字符。同一 client + 同一 key 不会重复执行。
Content-Typestring否POST 请求体建议用 application/json。

Key 安全

不要把 Key 写进前端代码或公开仓库。建议放服务端环境变量或密钥管理服务。发现泄漏立即吊销。

计费

扣费走招聘者角色钱包余额 + 资源包，余额不足返回 402 insufficient_points。响应里的 billing 对象同时给出 point_cents（精确子单位）与 points（展示积分）。

参数类型必填说明
简历解析 resumes/parse按页否TextIn xParse 0.05 积分/页（5 point_cents/页），不向上取整
人岗匹配 matches/resume-jd按次否固定 1 积分/次（100 point_cents），与模型消耗无关
批量筛选 batches/screen按候选人否1 积分/位候选人，失败项不扣费，异步结算
JD 优化 jds/optimize按 token否按模型实际消耗，最低 1 积分/次
查询批量任务 batches/:id免费否GET 接口不扣费

批量任务计费时机

批量筛选首响应 billed_point_cents 为 0，真实费用按候选人异步结算，以 GET 查询接口返回为准。首响应额外给出 estimated_point_cents 预估。

限流与配额

参数类型必填说明
daily_request_limitinteger否每个 client 每日请求上限，默认 1000。
monthly_request_limitinteger否每个 client 每月请求上限，默认 30000。

配额按 client 统计，只计 started 与 succeeded 状态请求，failed 不占配额。两者都为 0 时不限流。超限返回 429 open_api_quota_exceeded，次日/次月自动恢复，或联系商务调高。

请求体限制：全局 75MB；简历解析 fileDataUrl 单字段上限 25,000,000 字符（超限 413）；简历文本 ≤12,000 字符，JD 文本 ≤8,000 字符；批量筛选单次 ≤20 份简历。

幂等性

请求头加 Idempotency-Key（最长 160 字符）。同一 client + 同一 key：

  • 首次成功 → 后续同 key 直接回放原响应
  • 正在执行 → 返回 409 idempotency_key_in_progress，稍后重试
  • 上次失败 → 返回 409 idempotency_key_failed_use_new_key，换新 key 重试

崩溃可重试

若请求因进程崩溃卡在 started 超 10 分钟，系统自动回收该记录，允许用同一 key 重新执行。失败请求不扣费，回收不会重复扣费。

错误处理

错误响应统一结构 { "ok": false, "error": "...", "message": "..." }。402 额外返回 required_point_cents / balance_point_cents / resource_point_cents。

状态错误码说明
400invalid_input请求参数校验失败，detail 返回具体字段问题
401unauthorized缺少或无效的 Bearer API Key
402insufficient_points钱包余额不足，返回所需与可用 point_cents
403recruiter_role_requiredAPI Key 绑定账号不是招聘者角色
404not_found批量任务不存在或不属于该 client
409idempotency_key_in_progress同一幂等键正在执行中，请稍后重试
409idempotency_key_failed_use_new_key该幂等键对应请求已失败，请用新键重试
413payload_too_large请求体或 data URL 超出上限
429open_api_quota_exceeded超出每 client 日 / 月请求配额
500open_api_error服务端内部错误，可重试；失败不扣费

重试策略：5xx 与网络超时可重试（失败不扣费）；429 等配额恢复；409 in_progress 等几秒同 key 重试；409 failed 换新 key；402 充值后重试。