📘 接口概述
本接口用于接收客户端(脚本/APP)上传的屏幕截图(Base64编码的图像),执行目标检测或图像保存操作。服务端基于深度学习模型分析图像,返回检测到的物体信息(标签、置信度、边界框)。支持可配置的识别阈值、输入尺寸以及图片保存选项。
✨ 核心特性
• 基于Base64图像传输,兼容绝大多数脚本环境(触动精灵/按键精灵/安卓Lua/JS)
• 灵活调整
• 可选图片保存至服务端(便于数据采集)
• 支持自定义目标缩放尺寸
• 统一返回JSON,包含
• 基于Base64图像传输,兼容绝大多数脚本环境(触动精灵/按键精灵/安卓Lua/JS)
• 灵活调整
Prob (概率阈值) 和 Nms (非极大值抑制) 参数以获得最佳识别效果• 可选图片保存至服务端(便于数据采集)
• 支持自定义目标缩放尺寸
Size,平衡速度与精度• 统一返回JSON,包含
Code 业务状态码
🔌 基础信息
- 协议:HTTP / HTTPS (建议生产使用HTTPS)
- 请求方式:POST
- Content-Type:application/json
- 字符编码:UTF-8
📤 请求规范
🔗 请求地址
POST http://101.91.144.59:9999/TYT
⚠️ 示例地址仅供调试,正式地址请前往后台项目配置获取(双击项目查看)。生产环境建议使用域名+HTTPS。
📦 请求头 (Headers)
| 字段 | 值 | 必填 |
|---|---|---|
| Content-Type | application/json | 是 |
📋 请求体参数 (JSON)
| 参数名 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| Byte | string | 是 | 屏幕截图的Base64编码字符串(支持PNG/JPEG,建议JPEG压缩后传输)。 | "iVBORw0KGgoAAAANS..." |
| Save | boolean | 否 | 是否保存原始图片到服务端(用于数据集收集)。默认 false。 | false |
| Size | integer | 否 | 模型输入尺寸(宽/高统一缩放),通常设为 320~640 之间。推荐后台测试最佳值。 | 640 |
| Prob | float | 否 | 置信度阈值,过滤低质量检测框。范围 0.0~1.0,值越高误报越少。 | 0.45 |
| Nms | float | 否 | NMS(非极大值抑制)IoU阈值,用于消除重叠框。值越小去重越严格。 | 0.55 |
💡 参数调优建议:
Size 越大精度越高但耗时增加;Prob 建议 0.3~0.6 之间根据场景调节;Nms 常用 0.45~0.6。可在后台测试页面获得最佳组合。
示例请求体
{
"Byte": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBD...",
"Save": false,
"Size": 640,
"Prob": 0.45,
"Nms": 0.55
}
📥 响应格式
✔️ HTTP状态码
| 状态码 | 说明 |
|---|---|
| 200 | 请求成功处理(业务结果以JSON内Code为准) |
| 400 | 客户端错误:参数缺失、Base64解码失败或图像无效 |
| 500 | 服务端内部错误 |
📄 响应体结构 (JSON)
| 字段 | 类型 | 描述 |
|---|---|---|
| Code | Integer | 业务状态码,200 代表识别成功,其余值表示失败或特定状态 |
| Message | String | 可选,额外的提示信息(如错误原因) |
| Detections | Array | 检测结果列表(仅成功时返回)。每个元素包含 label, confidence, bbox |
📎 检测结果对象
| 字段 | 类型 | 示例 |
|---|---|---|
| label | string | "person", "car", "cat" |
| confidence | float | 0.92 |
| bbox | array[4] | [x1, y1, x2, y2] 边界框坐标 |
✅ 成功响应示例
{
"Code": 200,
"Message": "success",
"Detections": [
{"label": "person", "confidence": 0.96, "bbox": [120, 200, 340, 520]},
{"label": "cell phone", "confidence": 0.78, "bbox": [400, 500, 480, 620]}
]
}
❌ 失败响应示例
{
"Code": 400,
"Message": "Invalid image data or base64 decode failed"
}
💻 多语言调用示例
以下示例涵盖了四种主流脚本环境:LuaEngine (NX平台)、触动精灵 (TSLib)、按键精灵 + ShanHai插件、JavaScript (OkHttp)。
所有示例均实现:截图 → 压缩/Base64编码 → 发送请求并处理响应。
📱 LuaEngine (NX)
import("com.nx.assist.lua.LuaEngine")
import("android.graphics.BitmapFactory")
import("android.util.Base64")
function CompressPicture(bitmap, quality)
local baos = ByteArrayOutputStream()
bitmap.compress(Bitmap.CompressFormat.JPEG, quality, baos)
local encoded = Base64.encodeToString(baos.toByteArray(), Base64.DEFAULT)
baos.close()
if bitmap and not bitmap.isRecycled() then bitmap.recycle() end
return encoded
end
local bitmap = LuaEngine.snapShot(0,0,0,0)
local base64Img = CompressPicture(bitmap, 80) -- 质量80%
local payload = {
Byte = base64Img,
Save = false,
Size = 640,
Prob = 0.45,
Nms = 0.55
}
local resp = httpPost("http://101.91.144.59:9999/TYT", jsonLib.encode(payload))
local data = jsonLib.decode(resp)
if data.Code == 200 then
print("检测到目标:", #data.Detections)
end
🎮 触动精灵 (Lua)
require("TSLib")
require("tsnet")
local ts = require("ts")
local json = ts.json
local imgPath = "/sdcard/screenshot.png"
snapshot(imgPath, 0, 0, 720, 1280) -- 自定义区域
local base64Data = imageBase64(imgPath)
local postData = {
Byte = base64Data,
Save = false,
Size = 640,
Prob = 0.45,
Nms = 0.55
}
local _, _, respBody = http.post("http://101.91.144.59:9999/TYT",
{postdata = json.encode(postData)})
local result = json.decode(respBody)
if result and result.Code == 200 then
for _, obj in pairs(result.Detections or {}) do
nLog(obj.label, obj.confidence)
end
end
🕹️ 按键精灵 + ShanHai
Import "ShanHai.lua"
Dim 图片路径="/sdcard/pic.png"
SnapShot 图片路径
Dim 文件数据 = file.Read(图片路径)
Dim 图片Base64 = ShanHai.Base64En(文件数据)
Dim 请求表 = {"Byte":图片Base64, "Save":False, "Size":640, "Prob":0.45, "Nms":0.55}
Dim jsonStr = Encode.TableToJson(请求表)
Dim 地址 = "http://101.91.144.59:9999/TYT"
Dim 响应 = Url.HttpPost({"url":地址, "data":jsonStr})
Dim 结果 = Encode.JsonToTable(响应)
If 结果["Code"] = 200 Then
TracePrint "识别成功,共有" & UBound(结果["Detections"])+1 & "个目标"
End If
🌐 JavaScript (通用/OkHttp)
// 示例基于auto.js或普通JS环境
let BitMap = screen.screenShot(640, 960, 100).compress('jpg', 30);
let base64Str = BitMap.toBase64();
let content = {
Byte: base64Str,
Save: false,
Size: 640,
Prob: 0.45,
Nms: 0.55
};
let url = "http://101.91.144.59:9999/TYT";
let response = new okHttp().json(url, JSON.stringify(content));
let data = JSON.parse(response);
if (data.Code === 200) {
console.log("检测结果:", data.Detections);
}
💡 通用流程:①截图 → ②图像压缩(JPEG/PNG → Base64) → ③构造JSON → ④POST请求 → ⑤检查Code字段。
⚠️ 不同环境压缩参数和截图API略有差异,但请求体完全一致。
⚠️ 注意事项与最佳实践
📸 图像处理建议
• Base64数据体积较大,推荐使用JPEG压缩(质量40~80)平衡清晰度和流量。
• 如果脚本支持,建议提前将截图缩放到接近
• 触动精灵/按键精灵的PNG无损压缩会导致Base64剧增,可用“图片压缩工具”预处理或转为JPEG。
• Base64数据体积较大,推荐使用JPEG压缩(质量40~80)平衡清晰度和流量。
• 如果脚本支持,建议提前将截图缩放到接近
Size 参数以减少传输负载。• 触动精灵/按键精灵的PNG无损压缩会导致Base64剧增,可用“图片压缩工具”预处理或转为JPEG。
⚙️ 参数优化
•
•
•
•
Prob 阈值太低易出现误检,太高可能漏检,从0.45开始双向调整。•
Nms 推荐 0.45~0.6,当目标密集时可适当降低。•
Size 越大处理时间越长,建议不超过640(精度与效率平衡点)。
🌐 网络与安全
• 生产环境务必更换为HTTPS地址,并添加鉴权Header(如Token)避免滥用。
• 设置合理的HTTP超时(5~10秒)。
• 请求地址不要硬编码发布,建议通过配置读取。
• 生产环境务必更换为HTTPS地址,并添加鉴权Header(如Token)避免滥用。
• 设置合理的HTTP超时(5~10秒)。
• 请求地址不要硬编码发布,建议通过配置读取。
🔁 错误排查速查表
• Code非200 :检查Base64有效性,图片是否损坏。
• 请求超时 :测试网络连通性,确认服务端IP/端口可达。
• 识别效果差 :重新采集典型截图到后台测试,校准Size和Prob。
• Code非200 :检查Base64有效性,图片是否损坏。
• 请求超时 :测试网络连通性,确认服务端IP/端口可达。
• 识别效果差 :重新采集典型截图到后台测试,校准Size和Prob。
📌 状态码对照
| Code | 含义 |
|---|---|
| 200 | 成功,返回检测列表 |
| 400 | 请求参数错误(缺少Byte或Base64解码失败) |
| 401/403 | 鉴权失败(若开启验证) |
| 500 | 服务端内部错误或模型推理异常 |
🚨 重要提醒:API地址
http://101.91.144.59:9999/TYT 仅供联调测试,生产环境请务必替换为后台独立分配的稳定地址。服务端可能会不定期维护,请关注后台公告。
📂 文件清理:截图保存的本地文件(如/sdcard/图片.png)上传后应及时删除,避免存储空间占用。