API v1 · RESTful
阅读文档 → 开通账号 → 首调 register → 联调 recognize。输入牛只正脸照片（手机或固定机位拍摄），输出唯一牛 ID、相似度与阈值判定、活体检测结论。
输出物：唯一牛 ID、相似度与阈值判定、活体检测结论
curl · 04 步
在开放平台控制台（user.niujinjin.com）用手机号 + 密码自助注册，无需等待商务开通。
在控制台创建 API Key（明文只显示一次），以 X-API-Key 或 Authorization: Bearer nj_... 携带；一枚 Key 一个余额，牛脸与估重 API 通用。
POST https://api.face.niujinjin.com/api/v1/recognition/register，写入牛只档案并拿到唯一牛 ID。
用测试集跑一遍识别与活体，核对相似度分布后再切生产账号。
# 注册牛只身份（multipart，写入牛只档案）
curl -X POST https://api.face.niujinjin.com/api/v1/recognition/register \
-H "X-API-Key: nj_api_points_<32hex>" \
-F "file=@cow_facing.jpg" \
-F "cowId=CN-2026-0001" \
-F "farmId=farm_wh_001"
# 识别 / 认证（JSON，photoUrl）
curl -X POST https://api.face.niujinjin.com/api/v1/recognition/recognize \
-H "X-API-Key: nj_api_points_<32hex>" \
-H "Content-Type: application/json" \
-d '{ "photoUrl": "https://api.face.niujinjin.com/uploads/xxx/cow_facing.jpg" }'
# => { "code": 0, "isMatch": true, "cowId": "CN-2026-0001", "similarity": 0.83 }返回体为 JSON · 相似度按阈值判定 · 阈值可按业务调整
Base URL · https://api.face.niujinjin.com
请求与响应示例均可复制，字段口径以 /openapi.json 为准
/api/v1/recognition/register注册牛只身份：写入牛只档案并生成唯一牛 ID
REQUEST
curl -X POST https://api.face.niujinjin.com/api/v1/recognition/register \
-H "X-API-Key: nj_api_points_<32hex>" \
-F "file=@cow_facing.jpg" \
-F "cowId=CN-2026-0001" \
-F "farmId=farm_wh_001"RESPONSE
{
"code": 0,
"cowId": "CN-2026-0001",
"message": "registered"
}/api/v1/recognition/recognize识别 / 认证：返回匹配的牛只 ID 与相似度（含活体）
REQUEST
curl -X POST https://api.face.niujinjin.com/api/v1/recognition/recognize \
-H "X-API-Key: nj_api_points_<32hex>" \
-H "Content-Type: application/json" \
-d '{ "photoUrl": "https://api.face.niujinjin.com/uploads/xxx/cow_facing.jpg" }'RESPONSE
{
"code": 0,
"isMatch": true,
"cowId": "CN-2026-0001",
"similarity": 0.83,
"liveness": "pass"
}/api/v1/cow/:id查询牛只档案：唯一 ID 关联的注册记录。注意：该端点不在 API Key 计费白名单内（用 API Key 调它会返回 403 / 3004），需专用账号，请联系商务开通
REQUEST
curl https://api.face.niujinjin.com/api/v1/cow/CN-2026-0001 \
-H "Authorization: Bearer <INTERNAL_JWT_TOKEN>"RESPONSE
{
"code": 0,
"cowId": "CN-2026-0001",
"farmId": "farm_wh_001",
"registeredAt": "2026-09-12T08:21:00+08:00"
}按 code 分支处理，2003 需按业务策略转人工
| Code | 含义 | 处理建议 |
|---|---|---|
| 0 | 成功 | 按响应体业务字段处理 |
| 1001 | 鉴权失败 / 令牌过期 | 重新获取访问令牌 |
| 1002 | 参数缺失或格式错误 | 核对请求体字段与类型 |
| 2001 | 未检测到牛脸区域 | 更换正面、光线充足的照片重试 |
| 2002 | 活体检测未通过 | 确认为活体拍摄而非照片翻拍 |
| 2003 | 相似度低于阈值，未命中 | 按业务策略转人工复核或补充注册 |
| 5000 | 服务内部错误 | 重试一次后仍未恢复请联系支持 |
其余语言可直接使用 RESTful API
仓库内提供仅依赖标准库的示例客户端（docs/api/sdk/python/nj_client.py）与 curl 示例，可直接抄用。刻意不发包，避免引入额外依赖与版本漂移。
接口为标准 RESTful + JSON，任何语言都可直接调用；请以下载的 OpenAPI 契约为准生成客户端。
EVALUATION · 评测与方法
评测方法与已知局限公开可查。标定使用真实农场采集的影像与同期实测称重记录，按统一流程完成验证与迭代。
01 · DATASET
数据来自真实牧场采集的牛只影像，覆盖多品种、多角度与不同光照条件；评估数据按牛只维度独立切分，避免同一头牛同时出现在两侧。
02 · METRICS
03 · THRESHOLD
识别结果按相似度阈值判定：阈值调高减少误接受、调低减少误拒绝，可按业务风险偏好调整。
04 · LIMITATIONS
接入过程中的常见问题
FAQ
在开放平台控制台（user.niujinjin.com）用手机号自助注册并创建 API Key 即可调用计费端点（X-API-Key，或 Authorization: Bearer nj_...），无需等待开通；如需 JWT 内部账号请联系商务。
可以。统一文档（www.niujinjin.com/api）与字段级接口页（api.face.niujinjin.com/docs）及 /openapi.json 都无需凭据即可查看；调用计费端点需要控制台自助创建的 API Key（X-API-Key）。
目前不提供已发布的 SDK 包，仅提供 Python 示例客户端与 curl 示例；接口为标准 RESTful + JSON，任何语言可直接调用，也可用我们提供的 OpenAPI 契约生成客户端。
register 与 recognize 均为同步 HTTP 接口，当前不提供 Webhook 异步事件推送；高吞吐场景请自行并发调用，或联系我们评估批量方案。响应时间受图片大小与并发量影响，建议在测试集上实测。
识别结果按相似度阈值判定：阈值调高减少误接受、调低减少误拒绝。金融押品与保险理赔建议取较高阈值并保留人工复核，出入库盘点可在压降误拒绝的前提下放宽。