今日水印相机照片验真

概述

今日水印相机 – 照片验真 Skill

概述

本 Skill 封装今日水印相机开放平台验真 API 的完整调用流程，支持：

1. 创建验真任务 — 提交照片（URL 或 Base64）进行异步批量验真
2. 查询验真结果 — 获取照片的时间真实性、地点真实性、防伪码真实性和拍摄信息
3. 生成验真报告 — 生成可视化验真报告图片

API 支持检测照片是否被 PS 修改、是否为翻拍、防伪码是否真实，以及提取拍摄时间、GPS 位置等信息。

前置条件

获取 API 凭证

使用本 Skill 需要先对接今日水印相机官方商务获取 API 凭证：

• 商务联系电话：13141152023
• 商务人员会提供与团队绑定的唯一 GroupKey 和 GroupSecret

在开始任何 API 调用之前，必须先向用户确认是否已有 GroupKey 和 GroupSecret。如果没有，指导用户拨打 13141152023 联系商务获取。

GroupKey 和 GroupSecret 是敏感凭证，不应写入代码或日志。从用户处获取后仅在内存中持有。

API 基础地址

https://openapi.xhey.top

签名认证

所有 API 请求需要进行双重 HmacSHA256 签名认证。详细算法和代码示例见 references/api_docs.md 第 3 节。

签名工具脚本位于 scripts/trutu_sign.py，可直接调用：

python scripts/trutu_sign.py <group_key> <group_secret> '<json_body>'

或在 Python 代码中以模块方式使用：

from trutu_sign import build_headers

headers = build_headers(group_key, group_secret, request_body_json)

API 调用流程

典型验真流程

1. 创建验真任务 (POST /v2/truth_build/create)
       │
       ▼
2. 轮询查询验真结果 (POST /v2/truth_build/query)
   直到 taskStatus=5（处理完成）
       │
       ▼
3. (可选) 生成验真报告 (POST /v2/truth_build/verify_report)

第一步：创建验真任务

端点：POST https://openapi.xhey.top/v2/truth_build/create

提交照片进行验真。照片可以通过两种方式提供：

• photoUrlList：照片的可公开访问 URL 列表（图片需支持 GET 直接下载）
• photoBase64List：照片的标准 Base64 编码列表（不含 data:image/...;base64, 前缀）

两种方式至少选其一，也可同时使用。推荐一批次少于 10 条，最多 50 条。

请求体示例：

{
    "photoUrlList": ["https://example.com/photo.jpg"]
}

或使用本地图片的 Base64：

{
    "photoBase64List": ["iVBORw0KGgoAAAANSUhEUgAA..."]
}

关键实现步骤：

1. 构建请求体 JSON 字符串
2. 调用 build_headers(group_key, group_secret, body_json) 生成签名头
3. 发送 POST 请求，Content-Type 为 application/json
4. 从响应 data.data[0].taskID 获取任务 ID

重要：返回的 taskID 是后续查询的关键标识，必须保存。

完整请求示例（Python）：

import json
import requests
from trutu_sign import build_headers

group_key = "your_group_key"      # 从用户获取
group_secret = "your_group_secret" # 从用户获取

body = json.dumps({
    "photoUrlList": ["https://example.com/photo.jpg"]
})

headers = build_headers(group_key, group_secret, body)
resp = requests.post(
    "https://openapi.xhey.top/v2/truth_build/create",
    data=body,
    headers=headers
)

result = resp.json()
task_id = result["data"]["data"][0]["taskID"]
print(f"任务已创建，taskID: {task_id}")

第二步：查询验真结果

端点：POST https://openapi.xhey.top/v2/truth_build/query

使用第一步返回的 taskID 查询验真进度和结果。

请求体：

{
    "taskID": "2061632364592914432"
}

轮询策略：

• 检查 data.taskStatus：
  • 1 = 未处理
  • 2 = 处理中
  • 5 = 处理完成 ✅
  • 6 = 任务撤销
• 建议每 2-5 秒轮询一次，直到 taskStatus=5
• 验真通常需要数秒到数十秒，视照片数量和大小而定

结果解读：

当 taskStatus=5 后，查看 data.list[].status：

验真通过时返回的信息：

• photoTime — 拍照时间
• photoAddress — 拍照地点
• lat / lng — 经纬度（gcj02 坐标系）
• antiFakeCode — 防伪码
• msg — 判定描述（如"时间真实、地点真实、防伪码真实"）

第三步（可选）：生成验真报告

端点：POST https://openapi.xhey.top/v2/truth_build/verify_report

根据验真任务 ID 生成可视化的验真报告图片（PNG 格式），返回 OSS 图片地址。

请求体：

{
    "taskID": "2061632364592914432",
    "timeout": 60
}

• timeout：超时时间（秒），默认 60，范围 5-120

返回：

• 成功：data.ossUrl 为报告图片地址
• 超时：code=504，msg 包含超时提示，可尝试增加 timeout 后重试

结果展示建议

向用户呈现验真结果时，按以下格式组织信息：

📸 验真结果
━━━━━━━━━━━━━━━━━━
状态：✅ 真实 / ❌ 不通过
描述：时间真实、地点真实、防伪码真实
拍照时间：2026年05月29日 19:30
拍照地点：虞城县·至信一路
防伪码：CXPT4TX469K29W
经纬度：34.384929, 115.839913
━━━━━━━━━━━━━━━━━━

如果验真不通过，清晰说明失败原因（如"非今日水印相机拍摄"或"分辨率过低"）。

错误处理

常见 HTTP 错误

最佳实践

1. 签名验证：如果签名失败，首先检查请求体 JSON 字符串是否与签名时完全一致（包括空格和字段顺序）
2. Base64 编码：使用标准 Base64（StdEncoding），不要添加 data:image/...;base64, 前缀
3. 轮询超时：为验真结果查询设置合理的轮询超时（建议最多等待 120 秒），避免无限等待
4. 批量限制：一批次不超过 50 条，推荐少于 10 条以获得更快响应
5. 数据隐私：API 承诺传输数据全程不存储、不落库

参考资源

• 完整 API 文档：references/api_docs.md
• 签名工具脚本：scripts/trutu_sign.py