年龄验证 (Age Verification)

k-ID 提供一组 API，用于以下场景的用户年龄验证。

API	场景
/age-verification/perform-access-age-verification	在访问某个功能、成人内容或产品本身之前验证用户年龄
/age-verification/perform-trusted-adult-verification	为实现可验证的家长同意(VPC)而进行可信成人(父母/监护人)验证
/age-verification/perform-facial-age-estimation	仅使用人脸年龄估算进行验证
/age-verification/perform-id-verification	仅使用政府签发的身份证件进行验证
/age-verification/perform-age-appeal	针对疑似未成年用户，在恢复产品访问前进行年龄验证

Age Verification API 在请求与响应格式上是标准化的。

请求体 (Request Body)

字段	说明	必填
jurisdiction	执行年龄验证的法域	是
criteria	年龄验证的判定条件	是
subject.email	若用户在其他场景已通过 k-ID 使用邮箱完成年龄验证，则直接返回原始年龄，无需再次估算或证明	否
subject.claimedAge	用户在年龄门槛(age gate)中申报的年龄，用作年龄估算参考	否
subject.id	跨多种验证方法用于报告多次失败尝试的标识符(临时会话 ID 或哈希化用户 ID)	否

示例:

{
  "jurisdiction": "US-CA",
  "subject": {
    "email": "user@example.com",
    "claimedAge": 23,
    "id": "3854909b-8888-4bed-9282-24b74c4a3c97"
  },
  "criteria": {
    "ageCategory": "DIGITAL_YOUTH_OR_ADULT"
  }
}

响应体 (Response Body)

成功请求会返回如下结构。

字段	说明
id	由 Age Verification 服务生成的唯一验证 ID
url	必须展示给用户以完成自我验证的年龄验证 URL

示例:

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/verify?token=eyJhbGciOi..."
}

Verification Result

当用户成功完成年龄验证，或在达到最大重试次数后仍未成功时，年龄验证结果通过两种方式传递：

1. 以 Verification.Result 事件的形式发送到已注册的 Webhook
2. 若将上述 URL 嵌入 iFrame，则以 window 消息(MessageEvent)发送到父窗口

访问 window 消息示例：

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result") {
    // 在此处理结果
    console.log("eventData", message);
  }
};

window.addEventListener("message", handleMessage);

window 事件与 Webhook 事件的 data 元素包含以下字段：

字段	说明
id	本结果对应的验证 ID
status	根据用户是否满足年龄标准返回 PASS 或 FAIL
ageCategory	用户在请求中指定法域下所属的年龄类别。支持值：adult、digital-youth、digital-minor
method	使用的验证方法。支持值：id-document、age-estimation、age-attestation、credit-card、social-security-number
failureReason	失败原因。支持值：age-criteria-not-met、max-attempts-exceeded、fraudulent-activity-detected（仅当 status 为 FAIL 时返回）
age	返回估算或已验证年龄的下界与上界，分别为 low 与 high

示例：

{
  "eventType": "Verification.Result",
  "data": {
    "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
    "status": "PASS",
    "ageCategory": "adult",
    "method": "id-document",
    "age": {
      "low": 25,
      "high": 25
    }
  }
}

window 事件处理示例：

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result" && ) {
    if (message.data.status === "PASS") {
      window.location.href = `https://www.example.com/success?verificationId=${message.data.id}`
    }
    if (message.data.status === "FAIL") {
      window.location.href = `https://www.example.com/fail?verificationId=${message.data.id}`
    }
  }
};

window.addEventListener("message", handleMessage);

Verification Error

若发生意外错误，会触发一条 Javascript 事件，以便您的实现能够优雅地处理该错误。

消息示例：

{
  "eventType": "Verification.Error",
  "method": "credit-card",
  "status": "ERROR"
}

查询验证状态 (Checking Verification Status)

除了通过 Javascript 与 k-ID Webhook 发送事件外，还可以主动查询某一验证的状态。这有助于处理在一段时间内 Webhook 不可达而错过状态事件的情况。使用 /age-verification/get-status API 获取状态。返回的数据结构与发送到 Webhook 的数据元素一致。

支持的验证方法 (Supported Verification Methods)

当用于产品、功能或内容的访问时，k-ID 提供多种方式来验证用户年龄。

方法	说明
age-estimation	隐私保护型人脸年龄估算；生物特征信息不会离开用户设备
id-verification	使用护照、驾驶证等政府签发证件验证年龄
age-attestation	由已验证的父母为其子女的年龄作出证明

k-ID 还提供仅用于可信成人验证的特定年龄证明方法。此外，某些方法（如 age-estimation）在部分法域不允许用于可信成人验证。

方法	说明
credit-card	允许成人提供有效信用卡以证明其达到合同年龄
social-security-number	结合社会保障号码与部分个人信息来证明年龄

年龄验证对接测试

在编写调用 k-ID API 的代码之前，您可以使用 API Key 和 API 文档 亲自尝试人脸年龄估算。

首先，按照进行一次简单的 k-ID API 调用的步骤操作。

随后在同一浏览器中调用 /age-verification/perform-facial-age-estimation。在列表中点击该 API。

接着点击 Try it out 按钮，再点击 Execute 按钮。

iFrame 在您的应用(或单独浏览器窗口)中使用的 URL 位于响应的 url 字段。将该 URL 复制到浏览器中。示例：

https://family.k-id.com/verify?token=...

随后会看到说明页面：

点击 Start 按钮亲自尝试一次人脸年龄估算。请注意为确保安全所需的活体检测(liveness)检查。在此演示中，扫描结果不会在视图中以可见方式显示，因为它会作为 Javascript 事件与 Webhook 调用发送。不会有摄像头信息离开您的设备。