REST API · v1

API 接入文档

通过异步 API 提交人像，共用现有积分余额，查看每次任务与扣费。

计费

API 每次成功测试消耗 1 积分，网站每次测试消耗 10 积分，共用同一积分余额。API 创建任务时预占 1 积分，最终失败仅退还一次。

使用 Authorization: Bearer 并授予所需权限。相同图片重试时复用同一个 Idempotency-Key，更换输入返回 HTTP 409。查询接口不扣积分。

接口列表

HTTP	权限范围
POST /api/v1/face-age/jobs	face-age:write
GET /api/v1/face-age/jobs/{id}	face-age:read
GET /api/v1/credits	credits:read
GET /api/v1/usage?page=1&pageSize=20	usage:read

创建异步任务

使用 multipart/form-data，仅提交一张 JPEG、PNG 或 WebP 图片（最大 5 MB）及下方 consent 字段。仅限已成年、提交本人照片并明确同意处理的用户。拒绝远程图片 URL 和额外参数。仅在发起新测试时生成新的幂等键。

curl -X POST 'https://fahrface.org/api/v1/face-age/jobs' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'image=@portrait.jpg' \
  -F 'consent=appearance-age-2026-10-21'

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "JOB_ID",
    "status": "queued",
    "age": null,
    "creditsCost": 1,
    "billingStatus": "reserved"
  }
}

轮询任务结果

创建成功返回 HTTP 202 和任务 ID，建议每 10–15 秒查询一次。queued、processing、retrying 为未完成，succeeded、failed 为终态。HF 唤醒可能需要数分钟。任务期限为 20 分钟，仍有效的工作租约最多再延后四分钟结算。

curl 'https://fahrface.org/api/v1/face-age/jobs/JOB_ID' \
  -H "Authorization: Bearer $FAHRFACE_API_KEY"

错误与限制

响应沿用 code/message/data。HTTP 400：请求或同意字段错误；401：密钥无效或过期；403：权限不足；402：余额不足；404：任务不存在或不属于账户；409：输入冲突；413/415：图片大小或类型错误；429：频率、并发或预算超限；503：服务不可用。请先查看 message，遵循 Retry-After，并复用原幂等键重试。

密钥有效期最长一年。预算统计预占与成功扣费，退款会恢复预算。每个账户每分钟最多 60 次请求，同时最多两个 API 任务。

照片暂存于私有存储，任务结束后删除，并有 24 小时生命周期兜底。HF 将处理照片；结果不是医疗建议、身份验证或年龄证明。