证件真伪检测

接口说明

代码示例

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <Your API Key>" \
  -H "X-Timestamp: <epoch_seconds>" \
  -H "X-Nonce: <random_nonce>" \
  -H "X-Signature: <Your Signature>" \
  -d '{
    "card_image": "https://storage.googleapis.com/your-bucket/path/xxx.jpg",
    "card_type": "NATIONALID"
  }' \
  "https://data-gateway-test.creditkernel.ai/idfd/api/v1/id-forgery/detect"

Request Url

• POST /idfd/api/v1/id-forgery/detect
• Content-Type: application/json
• 调用模式：同步。请求返回即为检测结果，无需再轮询任务状态。

环境地址：

完整调用地址为 Base URL 拼接请求路径，例如测试环境：

https://data-gateway-test.creditkernel.ai/idfd/api/v1/id-forgery/detect

Request Header Parameters

Signature Canonicalization (MUST/SHOULD)

如接入方启用请求签名，请按以下规范执行：

1. 签名串格式（MUST）

签名原文（base string）必须按以下顺序并使用 \n 拼接：

METHOD\nRAW_PATH\nSORTED_QUERY\nBODY_SHA256\nTIMESTAMP\nNONCE

其中本接口的 RAW_PATH 固定为 /idfd/api/v1/id-forgery/detect，METHOD 为 POST，无 query 时 SORTED_QUERY 为空串（仍占一行）。

签名算法与编码（MUST）：

• 算法固定为 HMAC-SHA256。
• X-Signature 固定为 Base64 编码输出。
• X-API-Key、X-Timestamp、X-Nonce、X-Signature 必传。

签名方法：
- 参考 签名介绍及生成 文档

Request Parameters

请求 Body：

card_type 支持枚举：
DriverLicense、NATIONALID、HealthID、PostalID、Passport、VotersCard、TINID、SSS、PRC、GSIS、UMID

card_image 支持两种形式（重点）

card_image 为同一个字段，但允许传入以下两种不同形式的内容，服务端会按内容自动识别：

图片格式要求：

• 服务端通过图片解析校验格式，仅支持 JPEG / PNG / WEBP，否则返回 400。
• 使用方式二（URL）时，请确保图片地址公网可访问、在白名单范围内且未超过大小上限。

请求体示例（方式一：Base64）：

{
  "card_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "card_type": "NATIONALID"
}

请求体示例（方式二：图片 URL）：

{
  "card_image": "https://storage.googleapis.com/your-bucket/path/xxx.jpg",
  "card_type": "NATIONALID"
}

Notes:

• card_image 与 card_type 均为必传字段。
• card_image 为图片 URL 时必须以 http:// 或 https:// 开头，并满足大小、白名单、内网访问等限制；为 Base64 时支持纯 Base64 或带 data:image/...;base64, 前缀。
• 图片格式仅支持 JPEG / PNG / WEBP，无法解析时返回 400。
• 请求未携带有效 X-API-Key 或签名头时，将直接拒绝请求。

Example of Success Response

调用成功（HTTP 200）时，返回检测结果，顶层结构为 request_id / status / error_message / result / pricing_strategy。

检测拒绝（疑似伪造，真实示例）：

{
  "request_id": "460d0b9d-19ae-4a52-ac22-6a53892ab916",
  "status": "success",
  "error_message": null,
  "result": {
    "result": "REJECT",
    "detail": "other",
    "card_type": "NATIONALID",
    "confidence": "high",
    "capture_medium": "unknown",
    "reject_reasons": ["other"],
    "explanation": "pasted/spliced portrait; hard edge around portrait area and guilloche stops at boundary."
  },
  "pricing_strategy": "PAY"
}

检测通过（真证，结构示意）：

{
  "request_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "success",
  "error_message": null,
  "result": {
    "result": "PASS",
    "detail": null,
    "card_type": "NATIONALID",
    "confidence": "high",
    "capture_medium": "document",
    "reject_reasons": [],
    "explanation": "no tampering detected; security features consistent."
  },
  "pricing_strategy": "PAY"
}

说明：status 为请求处理状态（成功为 success）；result.result 为检测结论（PASS / REJECT）。detail、capture_medium、reject_reasons 中的具体枚举字符串及 explanation 文案以服务端实际返回为准，PASS 示例仅为结构示意。

Example of Business Error Response

输入校验失败（如缺少必填字段、card_image 无法解析、图片格式不支持）时，status 非 success、error_message 给出原因、result 为 null，HTTP 状态码可能为 400：

{
  "request_id": "eef65760-12bd-4414-a8eb-25483de36012",
  "status": "failed",
  "error_message": "unsupported image format, only JPEG/PNG/WEBP allowed",
  "result": null,
  "pricing_strategy": "FREE"
}

说明：错误响应中 status、error_message 的具体取值以服务端实际返回为准，上例仅为结构示意。租户身份 / 签名相关的失败由网关层拦截，返回下文“网关错误响应”格式。

Example of Gateway Auth Error Response

{
  "timestamp": "2026-05-13T10:37:05.612Z",
  "path": "/idfd/api/v1/id-forgery/detect",
  "status": 401,
  "code": "GATEWAY_UNAUTHORIZED",
  "message": "签名校验失败",
  "requestId": "60afbeb9-8"
}

{
  "timestamp": "2026-06-14T03:59:43.869Z",
  "path": "/idfd/api/v1/id-forgery/detect",
  "status": 429,
  "code": "GATEWAY_QUOTA_EXHAUSTED",
  "message": "租户调用总配额已用尽",
  "requestId": "..."
}

{
  "timestamp": "2026-06-14T04:53:10.972Z",
  "path": "/idfd/api/v1/id-forgery/detect",
  "status": 429,
  "code": "GATEWAY_RATE_LIMITED",
  "message": "请求过于频繁",
  "requestId": "1d13ad16-9988"
}

Response Description

业务响应字段（顶层）：

result 对象字段：

result.result（DetectionResult）含义

注意：顶层 status 为 success 且内层 result.result 为 REJECT，表示请求已成功处理完毕，但业务结论为拒绝；这不等价于 HTTP 4xx/5xx 传输层错误。

result.detail（RejectDetail）具体含义

PASS 时 detail 为 null；REJECT 时为下列枚举之一：

reject_reasons 通常为上述原因的数组形式；PASS 时为空数组。

result.capture_medium（CaptureMedium）

常见取值：original_photo、retake、screenshot、scan、photocopy_bw、photocopy_color、unknown。

网关错误响应字段：

Response Code

业务状态（顶层 status）：

计费策略（顶层 pricing_strategy）：

计费以业务返回的 pricing_strategy 为准：PAY 为计费请求，FREE 为不计费请求。

网关状态码（常见）：

Signature Authentication

当前接入模式仅支持 API Key + 请求签名：

• X-API-Key：租户固定调用密钥
• X-Timestamp：秒级时间戳
• X-Nonce：请求唯一随机串
• X-Signature：按“Signature Canonicalization”章节生成

签名串中的 RAW_PATH 使用本接口路径 /idfd/api/v1/id-forgery/detect；BODY_SHA256 按 application/json 规则先对 Body 做 JCS 规范化再做 SHA-256（小写 hex）。详细规则及可自验样例见 签名介绍及生成 文档。

Glossary

• API Key：租户调用身份凭证，放在请求头 X-API-Key
• Timestamp：签名时间戳，单位秒
• Nonce：签名随机串，用于防重放
• requestId：调用链追踪 ID，建议租户每次请求唯一
• card_image：证件图片入参，支持图片 Base64 或图片 URL 两种形式
• card_type：证件类型，取值见证件类型枚举
• status：请求处理状态，成功为 success
• result.result：检测结论，PASS 为真证、REJECT 为疑似伪造
• confidence：检测置信度，high / medium / low
• capture_medium：采集介质推断（CaptureMedium 枚举）
• explanation：检测结论的文字说明
• pricing_strategy：计费策略，PAY 计费、FREE 不计费