相机控制协议:HTTP 命令参考
DriftSee 开发者文档 · 2026.11.18
查询相机配网、预览、拍录、参数及媒体文件管理的 HTTP 命令。
提取码:gnts · SDK 1.0.0 · 开发预览 · Android / iOS
本页内容
XL Pro / X5 / X5 Mini 接入要求
连接前先读取相机型号和固件版本。手机与相机须位于可互通的局域网;相机发现使用 UDP 5555。已知 IP 时可直接连接。
建议先使用 720P、30 帧/秒、2 Mbps 视频配置,联通后再按目标型号和固件支持的档位调整。分辨率、帧率和码率应显式填写,避免不同配网入口的默认值差异。
以下参数已按当前三个型号的代码路径核对。型号与固件可能影响单位和生效条件;每次设置后读取 get_camera_status 确认实际值。
| 型号 | 2 Mbps 示例与改参要求 |
|---|---|
| XL Pro | HTTP: stream_bitrate=250000 Byte/s 停止录像;副码流还受主录像分辨率和 hd_record 设置约束。 |
| X5 | HTTP: stream_bitrate=2000000 bit/s 停止录像、RTSP 预览和 RTMP 推流,在主码流待机状态修改。 |
| X5 Mini | HTTP: stream_bitrate=2000000 bit/s 停止录像、RTSP 预览和 RTMP 推流,在主码流待机状态修改。 |
码率单位与数值边界
| 入口 / 参数 | 单位与示例 |
|---|---|
| fmcam.conf: stream_bitrate | 三个型号均为 bit/s;2000000 = 2 Mbps。 |
| start_rtmp_with_param ... &stream_bitrate= | 三个型号均按配置文件使用 bit/s;2000000 = 2 Mbps。 |
| HTTP: stream_bitrate= | XL Pro 为 Byte/s;X5 / X5 Mini 当前代码为 bit/s,按上表填写。 |
| HTTP: video_bitrate= | 三个型号均为 Byte/s;500000 = 4 Mbps。 |
| get_camera_status: stream_bitrate | 返回实际编码码率,单位为 bit/s。 |
独立 HTTP 流码率参数应为正整数。XL Pro 的有效边界为大于 12500、至 5625000 Byte/s;X5 / X5 Mini 为 100000~45000000 bit/s。这些是代码的数值边界;首次联调请使用上表的 2 Mbps 配置,并根据网络与画面效果调整。
分辨率与帧率写法
| 视频配置 | 配置文件 / RTMP 启动参数与独立 HTTP 参数 |
|---|---|
| 1080P | stream_resolution=1080P HTTP: stream_res=3 |
| 720P | stream_resolution=720P HTTP: stream_res=4 |
| WVGA | stream_resolution=WVGA HTTP: stream_res=5 |
HTTP 枚举 0、1、2 分别表示 4K、4KUHD、27K,不能写成 0 = 1080P。高分辨率和高帧率组合须由目标型号的录像档位支持。第一次联调使用 720P / 30 fps;需要 25 fps 时显式写入 fmcam.conf,并核对状态返回。
当前独立 HTTP stream_framerate 入口会拒绝 24、25、48、100、120、200、240;50、60 还受分辨率档位限制。video_framerate 的 CGI 转换将 25 映射到 30、50 映射到 60。不要仅根据返回成功推断实际帧率。
常用控制参数
| 参数 | 三个型号的通用写法 |
|---|---|
| dzoom | 0~10;0 表示关闭数字变焦。 |
| mic_sensitivity | 0~5;按相机实际音量需求选择档位。 |
| led / stamp / thm | 0:关闭;1:开启。 |
| exposure | 0、1、2、3、4 分别对应曝光补偿 0、+1、+2、-1、-2。 |
| filter | 0:标准;1:鲜艳;2:低照度。 |
| fov | 90、115、140;实际生效还受录像档位约束。 |
| language | 0:英文;1:中文。 |
三型号共用的 RTSP 起步配置
在 SD 卡根目录创建 fmcam.conf,并将公司示例 Wi-Fi 名称与密码替换为实际网络信息。
stream_type=rtsp router_ssid=DRIFTSEE_WIFI router_password=CHANGE_ME stream_resolution=720P stream_framerate=30 stream_bitrate=2000000 stream_audio=1
通话音源与改参顺序
SDK Demo 的手机麦克风链路输出 AAC-LC、16 kHz、双声道;外部 RTSP 音源按同一配置准备,并确保相机可以访问。相机来向声音以 RTSP 中实际音轨为准。
修改参数前,先结束通话并停止预览、推流和录像;完成参数设置后读取 get_camera_status,再恢复预览或通话。HTTP Status=1 表示指令已受理,最终参数和两路音频仍需分别确认。
Drift 相机提供开放 API,便于开发者构建定制应用。本文介绍如何获取相机实时视频,以及如何远程控制和配置相机。
应用可通过 RTSP 协议获取 Drift 相机的实时视频。完成配置后,相机作为视频流服务器,电脑或手机上的应用通过 RTSP 地址拉取视频。
除了作为 RTSP 服务器,Drift 相机还可将实时视频推送至云端或局域网内的 RTMP 服务器。
Wi-Fi 配网
Drift 相机以 Station(客户端)模式接入 Wi-Fi 路由器或手机个人热点,应用通过同一网络访问相机。
相机支持两种配网方式:通过配置文件填写 Wi-Fi 和视频流参数,或扫描包含配网信息的二维码。
1.1 配置文件
创建名为 fmcam.conf 的文本文件,按实际网络填写以下内容,并保存至相机存储卡根目录。请确认文件扩展名为 .conf。
router_ssid=xxxxxx router_password=12345678 stream_type=rtsp stream_resolution=720P stream_bitrate=2000000 stream_framerate=30
例如:

说明:
a)将 router_ssid 和 router_password 分别替换为 Wi-Fi 路由器或手机热点的名称与密码。
b)视频流分辨率可设为 480P、720P 或 1080P。码率 2000000 对应 2 Mbps;帧率可选 30 或 60。各型号的推荐配置如下:
- XL Pro:先使用 720P、2000000 bit/s、30 帧/秒,再按上方型号表调整。
- X5:先使用 720P、2000000 bit/s、30 帧/秒,再按上方型号表调整。
- X5 Mini:先使用 720P、2000000 bit/s、30 帧/秒,再按上方型号表调整。
c)存储卡中存在 fmcam.conf 时,相机每次开机都会自动启用 Wi-Fi,并作为视频流服务器运行。如需停用,删除该文件即可恢复常规使用。相机连接 Wi-Fi 后,也可按 Wi-Fi 按钮断开连接。
1.2 扫描二维码
应用与相机接入同一网络后即可通信。应用生成包含路由器名称和密码的二维码,相机扫码获取信息后自动连接路由器。
二维码内容格式:
17|router_ssid|router_password|stream_type
字段说明:
- 17:固定值,表示二维码类型。
- router_ssid:Wi-Fi 名称,不可为空。
- router_password:Wi-Fi 密码,可以为空。
- stream_type:视频流类型,仅支持 RTSP。
例如:

可使用二维码生成工具(例如 https://www.qr-code-generator.com/)将上述文本生成二维码。开发自己的应用时,可参考以下开源项目。
ZXing(“Zebra Crossing”):适用于 Java 和 Android 的条码扫描库。
https://github.com/zxing/zxing
获取相机 IP 地址
相机连接 Wi-Fi 后,会向同一网络内的手机或电脑发送 UDP 广播,广播包含建立连接所需的信息。应用获取相机地址后,即可发送 HTTP 命令进行控制。
UDP 广播端口为 5555,报文内容格式如下:
5|cam_serial|cam_model|phone_uuid|rtmp_status
字段说明:
- 5:固定值,表示广播类型。
- cam_serial:相机序列号。
- cam_model:相机型号。
- phone_uuid:可在 fmcam.conf 中通过 phone_uuid=****** 设置,最多 64 个字符;未设置时此字段为空。
- rtmp_status:相机状态,默认值 N 表示常规状态,当前未进行直播。
注意:可从 UDP 报文头中获取发送端的相机 IP 地址。
例如:
"5|86QHPFKVRIR0AB36|X5||N"
- 86QHPFKVRIR0AB36 为相机序列号。
- X5 为相机型号。
- phone_uuid 未设置。
- N 表示相机处于常规状态。
获取相机实时视频
连接建立后,应用可使用 VLC、ijk 或 vitamio 等播放器拉取相机实时视频。RTSP 地址格式为 rtsp://相机IP/live。
1)在电脑上安装 VLC 播放器。
2)获取相机 IP 地址,例如 192.168.4.148。
3)打开 VLC,选择“媒体 → 打开网络串流”,在地址栏中输入 rtsp://192.168.4.148/live。

4)点击“播放”,即可查看相机实时画面。
将实时视频推送至 RTMP 服务器
连接建立后,应用可通过以下 HTTP 接口控制相机向 RTMP 服务器推流。先获取相机 IP 地址(例如 192.168.4.148),再发送开始或停止直播命令。
4.1 启动 RTMP 直播
http://192.168.4.148/cgi-bin/foream_remote_control?start_rtmp_with_param=192.168.3.133:1935/live/5&stream_res=720P&stream_bitrate=2000000
其中,192.168.3.133:1935/live/5 表示 RTMP 服务器地址,省略 rtmp:// 前缀。
该命令也可同时设置直播分辨率和码率。
注意:若 RTMP 地址包含字符【&】,请将其替换为【***】。
例如:
原 RTMP 地址:
"rtmp://wxalivepush.weixin.qq.com/live/wx3059da5fb34ccef3-4?txSecret=bc91766cea0589c907c764cdf41d0047&txTime=629f7600"
替换后的地址:
"rtmp://wxalivepush.weixin.qq.com/live/wx3059da5fb34ccef3-4?txSecret=bc91766cea0589c907c764cdf41d0047***txTime=629f7600"
4.2 停止直播
http://192.168.4.148/cgi-bin/foream_remote_control?stop_rtmp
控制相机拉取 RTSP 音频
Drift 相机既可提供 RTSP 视频流,也可从远程 RTSP 服务器拉取并播放音频。音频格式须为 AAC、双声道、16 kHz 采样率。
1)设置相机的 rtsp_url 音频地址
http://192.168.5.181/cgi-bin/foream_remote_control?rtsp_url=rtsp://192.168.5.53/audio_test_file.aac
2)设置 RTSP 音频地址并开始播放
http://192.168.5.181/cgi-bin/foream_remote_control?start_rtsp=rtsp://192.168.5.53/audio_test_file.aac
3)停止播放音频流
http://192.168.5.181/cgi-bin/foream_remote_control?stop_rtsp
注意:上述示例的相机 IP 为 192.168.5.181,使用时请替换为实际相机 IP。
播放网络或存储卡中的音频文件
Drift 相机还可播放远程服务器或存储卡上的音频文件,音频格式须为 AAC、双声道、16 kHz 采样率。
1)播放相机存储卡中的音频文件
http://192.168.5.181/cgi-bin/foream_remote_control?play_audio_file=/tmp/SD0/audio_test_file.aac
将音频文件(如 audio_test_file.aac)放入相机 Micro SD 卡,发送上述命令即可播放。
audio_test_file.aac 必须采用 AAC 编码、双声道和 16 kHz 采样率。
示例音频地址:
http://www.driftlife.co/download/audio_test_file.aac
2)播放网络音频文件
http://192.168.5.181/cgi-bin/foream_remote_control?play_audio_url=http://www.driftlife.co/download/audio_test_file.aac&file_size=23316
此接口需要两个参数:音频文件的下载地址,以及文件大小。
相机控制
连接建立后,应用可通过 HTTP 接口控制相机。先获取相机 IP 地址(例如 192.168.4.148),再发送以下命令。
7.1 基本操作接口
1)数字变焦
http://192.168.4.148/cgi-bin/foream_remote_control?dzoom=1
dzoom 的取值范围为 0~10,0 表示不启用数字变焦。
2)开始录像
http://192.168.4.148/cgi-bin/foream_remote_control?start_record
3)停止录像
http://192.168.4.148/cgi-bin/foream_remote_control?stop_record
4)切换至录像模式
http://192.168.4.148/cgi-bin/foream_remote_control?switch_video_mode
5)切换至拍照模式
http://192.168.4.148/cgi-bin/foream_remote_control?switch_photo_mode
6)拍照
拍照前请确认相机处于拍照模式;可先发送 switch_photo_mode 命令切换模式。
http://192.168.4.148/cgi-bin/foream_remote_control?take_photo
7)恢复设置
http://192.168.4.148/cgi-bin/foream_remote_control?reset_setting
8)重启相机
http://192.168.4.148/cgi-bin/foream_remote_control?reboot
9)关闭相机
http://192.168.4.148/cgi-bin/foream_remote_control?power_off
11)指定参数录像
http://192.168.4.148/cgi-bin/foream_remote_control?record_with_param=PriName&sec_id=SecName
该接口可为录像文件设置自定义名称。PriName 和 SecName 仅支持字母和数字,生成的名称格式为 Priname_Secname。可通过 mediaInfo 接口查询此名称。
例如:
依次向相机发送以下命令:
http://192.168.4.148/cgi-bin/foream_remote_control?record_with_param=T002&sec_id=L0000001 http://192.168.4.148/cgi-bin/foream_remote_control?stop_record http://192.168.5.62/cgi-bin/foream_remote_control?mediaInfo
相机返回的文件信息示例:
{
"path": "100MEDIA\\VID00024.MP4",
"name": "T002_L0000001",
"time": "2024-01-01 00:38:55",
"size": "69512330"
}
7.2 相机参数设置
1)设置 LED 指示灯
http://192.168.4.148/cgi-bin/foream_remote_control?led=1
取值说明:1 为开启,0 为关闭。
2)设置曝光补偿
http://192.168.4.148/cgi-bin/foream_remote_control?exposure=1
取值说明:0 对应 0,1 对应 +1,2 对应 +2,3 对应 -1,4 对应 -2。
3)设置滤镜
http://192.168.4.148/cgi-bin/foream_remote_control?filter=1
取值说明:0 为标准,1 为鲜艳,2 为低照度。
4)设置麦克风灵敏度
http://192.168.4.148/cgi-bin/foream_remote_control?mic_sensitivity=1
取值范围为 0~5,分别对应各档麦克风灵敏度。
5)设置日期时间水印
http://192.168.4.148/cgi-bin/foream_remote_control?stamp=1
取值说明:0 为关闭日期时间水印,1 为开启。
6)设置视场角
http://192.168.4.148/cgi-bin/foream_remote_control?fov=140
可选值为 140、115、90。
7)设置缩略图文件
http://192.168.4.148/cgi-bin/foream_remote_control?thm=1
可选值为 0 或 1。
8)设置相机语言
http://192.168.4.148/cgi-bin/foream_remote_control?language=1
取值说明:0 为英文,1 为中文。
9)设置相机时间
http://192.168.4.148/cgi-bin/foream_remote_control?set_time=2021-03-01_09:35:00
此示例将相机时间设置为 2021/3/1 9:35。
7.3 实时视频参数
先结束预览、推流与录像,再修改分辨率和帧率。三个型号的码率单位见本页型号参数表。
1)720P 分辨率(1080P 用 3,WVGA 用 5)
http://CAMERA_IP/cgi-bin/foream_remote_control?stream_res=4
2)2 Mbps 码率:XL Pro
http://CAMERA_IP/cgi-bin/foream_remote_control?stream_bitrate=250000
2)2 Mbps 码率:X5 / X5 Mini
http://CAMERA_IP/cgi-bin/foream_remote_control?stream_bitrate=2000000
3)30 帧/秒
http://CAMERA_IP/cgi-bin/foream_remote_control?stream_framerate=30
7.4 录像参数
在停止录像后设置。video_res 与 stream_res 共用分辨率数值枚举;分辨率与帧率组合须由目标型号和固件支持。
1)1080P 录像分辨率
http://CAMERA_IP/cgi-bin/foream_remote_control?video_res=3
2)4 Mbps 录像码率:三个型号均填写 500000 Byte/s。
http://CAMERA_IP/cgi-bin/foream_remote_control?video_bitrate=500000
3)30 帧/秒;设置后读取状态确认实际档位。
http://CAMERA_IP/cgi-bin/foream_remote_control?video_framerate=30
7.5 相机状态
1)获取 XL Pro、X5、X5 Mini 相机当前状态
http://192.168.4.148/cgi-bin/foream_remote_control?get_camera_status
相机以 XML 格式返回状态,示例如下:
<Response>
<Status>1</Status>
<Cam_Status>
<camera_status>
<capture_mode>0</capture_mode>
<battery>100</battery>
<sd_free>15804576</sd_free>
<sd_total>31166464</sd_total>
<rec_time>0</rec_time>
<fw_ver>1127</fw_ver>
<model_name>X5_Mini</model_name>
<time>2024-05-10 12:12:54</time>
</camera_status>
<video_setting>
<res>2</res>
<framerate>30</framerate>
<bitrate>2000000</bitrate>
<quality>0</quality>
</video_setting>
<stream_setting>
<stream_res>0</stream_res>
<stream_framerate>24</stream_framerate>
<stream_bitrate>2000000</stream_bitrate>
</stream_setting>
<camera_setting>
<dzoom>0</dzoom>
<filter>0</filter>
<exposure>0</exposure>
<mic>5</mic>
<led>1</led>
<fov>140</fov>
<thm>0</thm>
<stamp>0</stamp>
<eis>0</eis>
<speaker_volume>6</speaker_volume>
<iso>0</iso>
<voice>2</voice>
<language>1</language>
<cardv>0</cardv>
<cardv_interval>60</cardv_interval>
<video_timelapse>0</video_timelapse>
<video_timelapse_interval>10</video_timelapse_interval>
<wifi_frequency>0</wifi_frequency>
</camera_setting>
</Cam_Status>
<websocket>0</websocket>
</Response>
主要状态字段:
| 字段 | 说明 |
|---|---|
| Status | 1 表示成功。 |
| capture_mode | 0:录像;1:拍照;2:延时摄影;3:连拍。X5 Mini 支持录像和拍照。 |
| battery | 剩余电量,单位为百分比。 |
| sd_free | SD 卡剩余容量,单位为 KB。 |
| sd_total | SD 卡总容量,单位为 KB。 |
| rec_time | 0 表示空闲;其他值表示当前录像时长。 |
| fw_ver | 固件版本。 |
| model_name | 相机型号。 |
| time | 相机日期与时间。 |
7.6 文件操作
1)列出 SD 卡媒体文件夹
http://192.168.4.148/cgi-bin/foream_remote_control?list_folders=/tmp/SD0/DCIM
列出相机 SD 卡 DCIM 目录下的所有媒体文件夹。
<Response>
<Folders>
{"Path":"100MEDIA"},
</Folders>
<Amount>1</Amount>
</Response>
2)列出 SD 卡媒体文件
http://192.168.4.148/cgi-bin/foream_remote_control?list_files=/tmp/SD0/DCIM
列出 SD 卡上的所有媒体文件。
<Response>
<Files>
{"Path":"PH000011.JPG","CreateTime":"Apr 26 19:12:50 2024","Size":2034256,"Thumb":1},
{"Path":"PH000012.JPG","CreateTime":"Apr 26 19:12:54 2024","Size":1632571,"Thumb":1},
{"Path":"VID00013.MP4","CreateTime":"Jan 01 00:38:54 2024","Size":69512330,"Thumb":1},
</Files>
<Amount>3</Amount>
</Response>
注意:
预览或下载媒体文件时,请使用以下地址:
http://192.168.4.148/DCIM/100MEDIA/VID00001.MP4 http://192.168.4.148/DCIM/100MEDIA/VID00002.MP4
3)列出自定义名称的录像文件
http://192.168.4.148/cgi-bin/foream_remote_control?mediaInfo
列出 SD 卡上所有设置了自定义名称的录像文件。
1
<Response>
<Status>1</Status>
<Files>
{
"files": [
{
"path": "DCIM\\100MEDIA\\VID00001.MP4",
"name": "priname_name123",
"time": "2022-09-12 14:22:40",
"size": "86620487"
},
{
"path": "DCIM\\100MEDIA\\VID00002.MP4",
"name": "priname_name456",
"time": "2022-09-12 15:22:40",
"size": "85420487"
}
]
}
</Files>
</Response>
4)删除 SD 卡媒体文件
http://192.168.5.56/cgi-bin/foream_remote_control?delete_media_file=100MEDIA/VID00003.MP4
注意:相机正在录像时,不可调用此接口。
5)批量删除 SD 卡媒体文件
http://192.168.5.56/cgi-bin/foream_remote_control?delete_media_multfiles=3|100MEDIA/VID00003.MP4|100MEDIA/VID00004.MP4|100MEDIA/VID00005.MP4
文件之间使用字符“|”分隔,第一项必须填写文件数量,最多为 40 个。相机正在录像时,不可调用此接口。
注意:iOS 应用需将字符【|】替换为【*%7C*】,例如:
http://192.168.5.56/cgi-bin/foream_remote_control?delete_media_multfiles=3*%7C*100MEDIA/VID00003.MP4*%7C*100MEDIA/VID00004.MP4*%7C*100MEDIA/VID00005.MP4