礼金簿识别平台 Logo
礼金簿识别 API 平台
对外开放的礼金簿识别接口

API 文档

完整的API接口说明和使用示例

接口地址与说明 同步 / 异步 · HMAC-SHA256 签名校验

同步识别(等待识别完成再返回)

同步接口
POST https://api.lijinbu.cn/v1/recognize

异步识别(推荐,用 requestId 轮询结果)

异步接口
POST https://api.lijinbu.cn/v1/recognize/async
GET  https://api.lijinbu.cn/v1/recognize/result/{requestId}

域名 `api.lijinbu.cn` 仅为示例,请替换为你自己的网关域名;路径 `/v1/...` 即为本服务的对外接口路径。

请求头(全部必填)

Header 名称 是否必填 说明
Content-Type 固定为 multipart/form-data,用于上传图片文件
X-API-Key 控制台生成的 API Key,用于标识调用方身份
X-Timestamp 当前 Unix 时间戳(秒),与服务端时间误差需在 5 分钟以内
X-Signature 使用 HMAC-SHA256 计算得到的签名,算法见下方“签名生成”章节
当前后端逻辑要求:X-API-Key、X-Timestamp、X-Signature 均为必填,缺少任一会返回 400 或 401 错误。

签名生成(HMAC-SHA256)

签名规则:先计算上传文件的 MD5 值,得到 file_md5; 然后拼接字符串 sign_string = timestamp + api_key + file_md5, 最后使用 api_secret 做 HMAC-SHA256 计算,十六进制输出即为 X-Signature

时间戳有效期为 ±5 分钟:如果 |server_time - timestamp| > 300, 后端会直接认为签名无效并返回 401。

JavaScript 示例

const crypto = require('crypto');

function generateSignature(timestamp, apiKey, apiSecret, fileMd5) {
  const signString = timestamp + apiKey + fileMd5;
  const signature = crypto
    .createHmac('sha256', apiSecret)
    .update(signString)
    .digest('hex');
  return signature;
}

// 使用示例
const timestamp = Math.floor(Date.now() / 1000).toString();
const fileMd5 = 'your_file_md5_hash';
const signature = generateSignature(timestamp, apiKey, apiSecret, fileMd5);

Python 示例

import hmac
import hashlib
import time

def generate_signature(timestamp, api_key, api_secret, file_md5):
    sign_string = f"{timestamp}{api_key}{file_md5}"
    signature = hmac.new(
        api_secret.encode('utf-8'),
        sign_string.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return signature

# 使用示例
timestamp = str(int(time.time()))
file_md5 = 'your_file_md5_hash'
signature = generate_signature(timestamp, api_key, api_secret, file_md5)

请求参数

参数名 类型 必填 说明
file File 图片文件(JPG、PNG),最大10MB

注意:当前版本中,请求头中的 X-API-Key、X-Signature、X-Timestamp 均为必填,并且签名必须验证通过才能调用接口。

同步识别接口调用示例

同步接口:POST /v1/recognize,服务端会等待识别完成后一次性返回完整结果。

异步识别(推荐)

同步接口会一直等待识别完成再返回;如果你希望更稳定(避免超时),推荐用异步接口: 先提交任务拿到 requestId,再轮询查询结果。

1)提交异步任务

POST /v1/recognize/async
curl -X POST https://api.lijinbu.cn/v1/recognize/async \
  -H "X-API-Key: your_api_key" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: your_generated_signature" \
  -F "file=@/path/to/image.jpg"

返回示例(立即返回,status=pending):

{
  "code": 200,
  "message": "success",
  "data": {
    "requestId": "a1b2c3d4e5f6",
    "identifyRecordId": 123456,
    "status": "pending"
  }
}

2)轮询查询结果

GET /v1/recognize/result/{requestId}
curl -X GET https://api.lijinbu.cn/v1/recognize/result/a1b2c3d4e5f6 \
  -H "X-API-Key: your_api_key" \
  -H "X-Timestamp: $(date +%s)" \
  -H "X-Signature: your_generated_signature"

如果仍在识别中(status=pending):

{
  "code": 200,
  "message": "success",
  "data": {
    "requestId": "a1b2c3d4e5f6",
    "identifyRecordId": 123456,
    "status": "pending"
  }
}

识别完成(status=success):

{
  "code": 200,
  "message": "success",
  "data": {
    "requestId": "a1b2c3d4e5f6",
    "identifyRecordId": 123456,
    "status": "success",
    "records": [
      { "name": "张三", "money": 500, "remark": "" }
    ],
    "total": 500,
    "recordCount": 1
  }
}

异步识别多语言调用示例(提交 + 轮询)

响应示例

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "name": "张三",
        "money": 500,
        "remark": "备注信息"
      },
      {
        "name": "李四",
        "money": 300,
        "remark": ""
      }
    ],
    "total": 800,
    "recordCount": 2,
    "status": "success",
    "requestId": 123456
  }
}

错误响应

{
  "code": 400,
  "message": "Invalid signature",
  "data": null
}

错误码说明

错误码 说明
200 成功
400 请求参数错误
401 签名验证失败
403 点数不足或余额不足
500 服务器内部错误

响应字段说明

字段名 类型 说明
code Integer 状态码(200表示成功)
message String 响应消息
data.records Array 识别结果数组,每个元素包含 name(姓名)、money(金额)、remark(备注)
data.total Number 总金额
data.recordCount Integer 识别记录数量
data.status String 识别状态(success/failed/pending)
data.requestId Long 识别记录ID,可用于查询详情

快速测试

您可以在控制台页面使用快速识别功能进行测试,或查看识别记录页面查看历史记录。