HTTP API
简介
T256s 用 USB 连接电脑时,除了作为 UVC 摄像头工作,还会向电脑提供一块 USB 网卡。设备在这块网卡上运行 HTTP 服务,可以读取设备信息、当前温度、伪彩画面和每个像素的原始温度。
http://192.168.17.1
浏览器打开这个地址,看到的是设备自带的网页;用 curl 或任意能发 HTTP 请求的语言访问同一批接口,拿到的是数据。
HTTP API 需要固件 26.40.0 或更高版本。查看当前版本的方法见系统更新。
HTTP 接口和 UVC 是两条独立的通道:
- UVC 输出视频画面。MJPEG 画面已经上色,颜色不再对应温度;Y16 是原始数据,使用时需要自己接驱动;
- HTTP 接口直接返回 JSON 温度、JPEG 画面和 TEMP16 原始温度,不需要驱动。
需要精确温度数值、批量采集,或者接入脚本和 AI 工具时,用 HTTP 接口更方便。
工作原理
相机连接电脑后,会同时提供 UVC 摄像头、USB 网卡和一块约 32 MB 的可移动磁盘。HTTP 服务运行在网卡上,电脑拿到地址后即可访问:
你的程序(curl / Python / AI 工具)
|
| HTTP
v
T256s http://192.168.17.1
|
+-- /api/v1/thermal 当前中心、最高、最低温度
+-- /frame.jpg 伪彩画面
+-- /frame.temp16 逐像素原始温度
其中:
- 设备固定使用
192.168.17.1/24,自己当 DHCP 服务器,给电脑分配192.168.17.2到192.168.17.20; - 读取接口不需要登录,返回的数据不做缓存;
- 连续视频流最多同时 4 路。
使用前准备
开始前,请先确认:
- 相机已用 Type-C 线连接电脑,并且电脑上能看到 UVC 摄像头;
- 系统里多出一块 USB 网卡,并已拿到
192.168.17.x地址。Windows 在「网络连接」中查看,Linux 用ip addr查看; - 浏览器打开
http://192.168.17.1能看到设备网页; - 电脑上可以使用
curl。Windows 10/11 自带curl.exe,在 PowerShell 中可以直接运行。
浏览器打不开
192.168.17.1时,先检查网卡有没有拿到地址。拿到169.254.x.x说明 DHCP 没有成功,可以给网卡设置静态地址192.168.17.100,掩码255.255.255.0。
接口一览
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/v1/device |
设备型号、固件、分辨率、支持的格式 |
| GET | /api/v1/network |
当前网段、设备地址和 DHCP 地址池 |
| PUT | /api/v1/network |
修改网段 |
| GET | /api/v1/thermal |
当前帧的中心、最高、最低温度 |
| GET | /api/v1/measurement |
测温参数(只读) |
| GET | /frame.temp16 |
单帧逐像素原始温度 |
| GET | /stream.temp16 |
连续原始温度 |
| GET | /frame.jpg?source=sr |
单帧超分伪彩画面 |
| GET | /frame.jpg?source=native |
单帧原生伪彩画面 |
| GET | /stream.jpg?source=sr |
连续超分伪彩画面 |
| GET | /stream.jpg?source=native |
连续原生伪彩画面 |
单帧接口
/frame.temp16、/frame.jpg也支持HEAD,只返回响应头,适合先探测尺寸和元数据长度。
查看设备信息
GET /api/v1/device 是接口入口,返回设备型号、固件、分辨率、支持的格式和并发上限。
curl http://192.168.17.1/api/v1/device
返回内容较长,下面只保留常用字段:
{
"device": { "model": "T256S", "firmware": "26.47.0" },
"sensor": { "native_width": 256, "native_height": 192 },
"network": { "segment": 17, "device_ip": "192.168.17.1" },
"streaming": { "max_stream_clients": 4 },
"formats": [
{ "id": "temp16", "frame": "/frame.temp16" },
{ "id": "jpg", "source": "device_sr",
"frame": "/frame.jpg?source=sr" },
{ "id": "jpg", "source": "device_native",
"frame": "/frame.jpg?source=native" }
]
}
写程序时,建议先请求一次这个接口,再按返回的 frame 和 stream 地址取数据,不要写死路径。固件之后增加格式或调整路径时,程序不用跟着改。
读取温度
当前温度
GET /api/v1/thermal 返回当前帧的中心、最高、最低温度,不需要下载图像,适合轮询和报警。
curl http://192.168.17.1/api/v1/thermal
{
"frame_number": 2070,
"timestamp_ms": 68681,
"valid": true,
"center": { "celsius": 40.79, "x": 128, "y": 96 },
"minimum": { "celsius": 39.48, "x": 7, "y": 169 },
"maximum": { "celsius": 41.91, "x": 254, "y": 2 }
}
其中:
frame_number是帧序号,每出一帧加一,可以用来判断有没有新数据;timestamp_ms是设备启动后的毫秒数,不是当前时间;- 坐标基于 256×192 的横向画面。伪彩画面是竖屏的,两者方向不同,在图上标注位置时按
recommended_rotation旋转一次。
相邻两帧的温度会有 0.5 ℃ 左右的抖动,判断温度是否在变化时,多采几次看趋势,不要只看一帧。
测温参数
GET /api/v1/measurement 返回设备当前使用的测温假设:
curl http://192.168.17.1/api/v1/measurement
{
"processing": "device",
"revision": 0,
"defaults": {
"emissivity": 0.95,
"distance_m": 1.0,
"reflected_temperature_c": 25.0
},
"limits": {
"emissivity": [0.01, 1.0],
"distance_m": [0.1, 100.0],
"reflected_temperature_c": [-40.0, 550.0]
}
}
发射率 0.95、距离 1 米、反射温度 25 ℃ 是设备侧测温模型实际使用的参数,接口只读,不能修改。测量光亮金属时,在表面贴一层电工胶带或喷哑光黑漆,比在软件里调参数更有效。
抓取画面
GET /frame.jpg 返回一张已经上好伪彩的 JPEG 画面,需要带 source 参数:
# 超分画面,480×640,约 180 KB
curl -o sr.jpg "http://192.168.17.1/frame.jpg?source=sr"
# 原生画面,192×256,约 40 KB
curl -o native.jpg "http://192.168.17.1/frame.jpg?source=native"
source=sr:经过设备端 AI 超分的画面,细节更清楚,体积更大;source=native:原生分辨率,体积小,适合低带宽预览;- 不带
source会返回404,错误码为format_not_supported。
响应头里的 X-Sipeed-Meta 是这一帧元数据的 Base64 编码,解码后可以读到中心、最高、最低温度,不用再请求一次温度接口:
curl -sI "http://192.168.17.1/frame.jpg?source=native" \
| grep -i x-sipeed
JPEG 画面已经上色,像素颜色不代表温度,不能从画面反推温度。需要逐像素温度时,用下一节的 TEMP16。
读取逐像素温度
记录格式
GET /frame.temp16 返回一条固定长度的记录,共 98424 字节:
| 段 | 长度 | 内容 |
|---|---|---|
| payload | 98304 字节 | 256×192 个小端 uint16,共 49152 个像素 |
| metadata | 120 字节 | 帧号、尺寸、温度系数、极值点等 |
payload 里是线性编码的原始值,按下式换算成摄氏温度:
摄氏温度 = 原始值 × temperature_scale + temperature_offset
当前固件的系数是 1/64 和 -273.15,即 ℃ = raw / 64 - 273.15,和 UVC Y16 的换算一致。换算时以元数据里的系数为准,不要写死。
下面的 Python 脚本读取一帧并打印最高温和最低温,只用标准库:
import struct, urllib.request, zlib
url = "http://192.168.17.1/frame.temp16"
raw = urllib.request.urlopen(url, timeout=5).read()
payload, meta = raw[:98304], raw[98304:]
crc = struct.unpack_from("<I", meta, 116)[0]
assert meta[:8] == b"SITHMETA"
assert zlib.crc32(meta[:116]) == crc, "元数据校验失败"
scale, offset = struct.unpack_from("<ff", meta, 48)
values = struct.unpack("<49152H", payload)
celsius = [v * scale + offset for v in values]
i = max(range(len(celsius)), key=celsius.__getitem__)
print(f"最高温 {celsius[i]:.2f} ℃ @ ({i % 256}, {i // 256})")
print(f"最低温 {min(celsius):.2f} ℃")
运行结果示例:
最高温 42.10 ℃ @ (254, 2)
最低温 39.48 ℃
元数据字段
元数据固定 120 字节,小端排列。常用字段如下:
| 偏移 | 字段 | 类型 | 说明 |
|---|---|---|---|
| 0 | magic |
char[8] |
固定为 SITHMETA |
| 8 | version_major / version_minor |
u8 |
当前为 1 / 0 |
| 10 | meta_bytes |
u16 |
固定为 120 |
| 12 | flags |
u32 |
位掩码。(flags & 0x1D) == 0x1D 表示温度字段可用,bit 5 表示 payload_crc32 有效 |
| 16 | frame_number |
u32 |
帧序号 |
| 24 | timestamp_ms |
u32 |
设备启动后的毫秒数 |
| 28 | payload_bytes |
u32 |
固定为 98304 |
| 32 | payload_crc32 |
u32 |
payload 的 CRC32 |
| 36 | width / height |
u16 |
256 / 192 |
| 40 | stride_bytes |
u16 |
固定为 512 |
| 44 | display_rotation |
u8 |
建议旋转量,当前为 3 |
| 48 | temperature_scale |
f32 |
温度斜率,当前为 0.015625 |
| 52 | temperature_offset |
f32 |
温度截距,当前为 -273.15 |
| 56 | center_temperature |
f32 |
中心点温度(℃) |
| 60 | minimum_temperature |
f32 |
全帧最低温(℃) |
| 64 | maximum_temperature |
f32 |
全帧最高温(℃) |
| 68 | center_x / center_y |
u16 |
中心点坐标 |
| 72 | minimum_x / minimum_y |
u16 |
最低温点坐标 |
| 76 | maximum_x / maximum_y |
u16 |
最高温点坐标 |
| 104 | measurement_config_id |
u32 |
测温配置版本,当前为 0 |
| 116 | meta_crc32 |
u32 |
前 116 字节的 CRC32 |
detector_temperature、source_low、source_high 当前为 NaN,calibration_id 和 nuc_table_index 未提供,读取时跳过即可。这些数值以元数据为准,不要写死在程序里。
连续读取
原始温度
GET /stream.temp16 会持续输出首尾相接的 98424 字节记录,中间没有分隔符,按固定长度切分即可:
curl -s http://192.168.17.1/stream.temp16 | python3 -c "
import sys
buf = b''
while True:
chunk = sys.stdin.buffer.read(65536)
if not chunk: break
buf += chunk
while len(buf) >= 98424:
rec, buf = buf[:98424], buf[98424:]
print('帧', int.from_bytes(rec[98304+16:98304+20], 'little'))
"
读到一半的数据要留在缓冲区里,凑够 98424 字节再解析。按 TCP 分片直接解析会把帧切坏。
伪彩画面
GET /stream.jpg 是标准的多段 JPEG 流,分隔符为 --sipeedframe,每段是一帧 JPEG,段头里同样带 X-Sipeed-Meta。
curl -s "http://192.168.17.1/stream.jpg?source=sr" \
| ffmpeg -f mpjpeg -i - -r 20 out.mp4
也可以把地址直接放进浏览器的 <img> 标签,画面会持续刷新。
并发上限
设备最多同时提供 4 路连续流。第 5 路会返回 409,错误码为 stream_limit_reached:
{
"ok": false,
"error": {
"code": "stream_limit_reached",
"message": "Maximum stream client count reached"
}
}
单帧接口不占这个名额。客户端断开后名额会释放;读取较慢的客户端不会拖慢设备采集,设备会丢掉写不出去的帧。
三路同时读取 15 秒(26.47.0,室内场景):
| 流 | 帧率 | 带宽 |
|---|---|---|
/stream.temp16 |
18.6 FPS | 14.7 Mbit/s |
/stream.jpg?source=sr |
18.6 FPS | 28.3 Mbit/s |
/stream.jpg?source=native |
18.7 FPS | 6.1 Mbit/s |
JPEG 的带宽和画面复杂度有关,噪声多、纹理多的场景体积更大。表中的数值来自一次室内测量,不是上限。
修改网段
PUT /api/v1/network 可以修改设备使用的网段,设备地址会变成 192.168.<网段>.1。
curl -X PUT http://192.168.17.1/api/v1/network \
-H "X-Sipeed-Request: 1" \
-H "Content-Type: application/json" \
-d '{"segment": 19}'
执行后设备会立即换成
192.168.19.1,电脑上的网卡需要重新获取地址。操作前先确认怎么改回来,把segment改回 17 再执行一次即可。
写接口要求三个条件同时满足:
- 请求头带
X-Sipeed-Request: 1; Content-Type为application/json;- 如果带了
Origin请求头,必须是设备自己的地址。
错误返回
接口出错时返回统一的 JSON:
{
"ok": false,
"error": {
"code": "not_found",
"message": "API endpoint not found"
}
}
常见错误:
| 状态码 | 错误码 | 说明 |
|---|---|---|
| 404 | not_found |
路径不存在,从 /api/v1/device 返回的地址里取 |
| 404 | format_not_supported |
格式不支持,检查 source 参数 |
| 409 | stream_limit_reached |
连续流超过 4 路 |
| 503 | frame_not_ready |
设备刚启动,还没有可用画面 |
| 400 / 415 / 403 | missing_request_guard / unsupported_content_type / origin_rejected |
写接口的请求头不符合要求 |
常见问题
浏览器打不开 192.168.17.1
请检查:
- 相机是否已经连接到电脑,电脑上是否出现 UVC 摄像头;
- 是否多出一块 USB 网卡,并且拿到了
192.168.17.x地址; - 换一根数据线或换一个 USB 口再试,部分线材只能供电,不能传数据。
浏览器能打开,但 curl 连不上
Windows 的 PowerShell 5.1 把 curl 当作 Invoke-WebRequest 的别名,参数不能直接套用。改用 curl.exe:
curl.exe http://192.168.17.1/api/v1/thermal
自己发请求时返回 302
用 socket 或框架直接拼 HTTP 请求时,如果 Host 头不是设备地址,设备会把它当成 Captive Portal 探测,返回 302 跳转到 http://ir.sipeed.com/。把 Host 设成 192.168.17.1(或 t256s.cam)即可。
请求 frame.jpg 返回 404
/frame.jpg 必须带 source 参数,例如 /frame.jpg?source=sr 或 /frame.jpg?source=native。不带参数时会返回 404 和 format_not_supported。
同时开多个视频流后请求失败
设备最多支持 4 路连续流,超出后返回 409。关掉暂时不用的流即可;只需要温度时,用 /api/v1/thermal 轮询,不占流的名额。
接口温度和热像仪屏幕显示对不上
常见原因:
- 两边读的不是同一帧,温度会随时间小幅变化;
- 设备刚上电,还没有达到热平衡,建议预热 2 分钟;
- 被测表面发射率低,例如光亮金属,测温本身会偏低或偏高;
- 屏幕上的数值按伪彩画面显示,接口里的坐标基于横向原始画面,标注位置时要旋转一次。
能不能通过接口修改发射率
不能。当前固件里 GET /api/v1/measurement 只读,发射率、距离和反射温度都固定在设备侧。
录下来的视频里没有温度数据
UVC 的 MJPEG 画面已经上色,颜色不代表温度。需要温度时,用 HTTP 的 TEMP16 或 /api/v1/thermal,不要从彩色画面反推。
改了网段之后连不上了
设备地址已经变成 192.168.<网段>.1,电脑需要重新获取地址。用浏览器打开新地址,再把 segment 改回 17 执行一次即可恢复。