SDK/API 开发者文档

简体中文

English

简体中文

English

主题

接口文档 ​

获取相机信息 ​

  • 使用GET /osc/info 获取设备信息，建议不要超过1次/秒
{
	"manufacturer": "Arashi Vision",
	"model": "Insta360 One2",
	"serialNumber": "IXE3619AYS76P6",
	"firmwareVersion": "v1.18.43",
	"supportUrl": "https://www.insta360.com/product/insta360-one2/",
	"endpoints": {
		"httpPort": 80,
		"httpUpdatesPort": 80
	},
	"gps": false,
	"gyro": true,
	"uptime": 48,
	"api": [
		"/osc/info",
		"/osc/state",
		"/osc/checkForUpdates",
		"/osc/commands/execute",
		"/osc/commands/status"
	],
	"apiLevel": [
		2
	],
    "_sensorModuleType": "4K",
	"_vendorVersion": "v1.1_build1"
}

_sensorModuleType模组类型目前仅ONER型号支持，类型包括4K/4K_Selfie Dual_Fisheye Leica/Leica_Selfie,Selfie表示镜头为自拍方向（与触摸屏在同一方向）

  • 使用POST /osc/state 获取设备状态，建议不要超过1次/秒 /osc/state 返回示例
{
	"fingerprint": "FPR_52923",
	"state": {
		"_cardState": "pass",
		"batteryLevel": 1,
		"storageUri": "http://192.168.42.1:80/DCIM/Camera01/"
	}
}

state._cardState：表示卡状态，可能的值是 noCard无卡、pass有卡且格式正确、noSpace有卡空间不足、invalidFormat有卡格式不正确、writeProtect有卡写保护、otherError未知错误 state.batteryLevel: 电量，0-1对应0-100的电量 state.storageUri: 相机内拍摄照片的存储路径

开始拍照前必须分别获取一次/osc/info 、/osc/state

  • 使用POST /osc/commands/execute 执行 camera.getOptions 获取相机的特性 camera.getOptions 参数示例：
json
{
  "name":"camera.getOptions",
  "parameters": {
      "optionNames": [
          "iso",
          "isoSupport",
    "shutterSpeed",
    "shutterSpeedSupport",
          "hdr",
          "hdrSupport",
          "totalSpace",
          "remainingSpace",
          "photoStitching",
          "photoStitchingSupport",
          "captureInterval",
          "captureIntervalSupport",
          "captureMode",
          "_videoType",
          "_videoTypeSupport",
          "_timelapseResolution",
          "_timelapseResolutionSupport",
          "_timelapseInterval",
          "_timelapseIntervalSupport",
          "exposureProgram",
          "exposureDelay",
          "exposureDelaySupport",
          "_topBottomCorrection",
          "whiteBalance",
          "whiteBalanceSupport",
          "_dateTime",
          "_MuteEnable",
          "_batteryCapacity",
          "_sysTimestamp"
      ]
  }
}

camera.getOptions 正确返回示例：

json
{
    "name": "camera.getOptions",
    "state": "done",
    "results": {
        "options": {
            "iso": 100,
            "isoSupport": [
                0,
                100,
                125,
                160,
                200,
                250,
                320,
                400,
                500,
                640,
                800,
                1000,
                1250,
                1600,
                2000,
                2500,
                3200
            ],
            "shutterSpeed": 0.001000,
            "shutterSpeedSupport": [
                0,
                120,
                100,
                80,
                60,
                50,
                40,
                30,
                15,
                8,
                2,
                1,
                0.500000,
                0.200000,
                0.100000,
                0.066660,
                0.033330,
                0.020000,
                0.016660,
                0.010000,
                0.008330,
                0.002000,
                0.001000,
                0.000500,
                0.000250,
                0.000125
            ],
            "hdr": "off",
            "hdrSupport": [
                "off",
                "hdr"
            ],
            "totalSpace": 0,
            "remainingSpace": 0,
            "photoStitching": "none",
            "photoStitchingSupport": [
                "none",
                "ondevice"
            ],
            "captureInterval": 3000,
            "captureIntervalSupport": {
                "minInterval": 3,
                "maxInterval": 120
            },
            "captureMode": "image",
            "_videoType": "normal",
            "_videoTypeSupport": [
                "normal",
                "timelapse"
            ],
            "_timelapseResolution": "5.7K",
            "_timelapseResolutionSupport": [
                "5.7K",
                "8K"
            ],
            "_timelapseInterval": 4,
            "_timelapseIntervalSupport": [
                0.2,
                0.5,
                1,
                2,
                4,
                10,
                30,
                60,
                120
            ],
            "exposureProgram": 2,
            "exposureDelay": 0,
            "exposureDelaySupport": [
                0,
                3,
                5,
                10,
                15,
                0
            ],
            "_topBottomCorrection": {
                "_topBottomCorrection": 0
            },
            "whiteBalance": "auto",
            "whiteBalanceSupport": [
                "auto",
                "incandescent",
                "fluorescent",
                "daylight",
                "cloudy-daylight"
            ],
            "_dateTime": "2023:03:23 16:05:41",
            "_MuteEnable": {
                "_MuteEnable": 0
            },
            "_batteryCapacity": {
                "powerType": 1,
                "powerLevel": 100
            },
            "_sysTimestamp": 60427274
        }
    }
}

camera.getOptions 参数错误返回结果:

{
	"name": "camera.getOptions",
	"state": "error",
	"error": {
		"code": "invalidParameterName ",
		"message": "parameter is not supported."
	}
}
  • 每次成功连接相机时，执行 camera.getOptions 判断相机是否支持机内拼接功能
{
  "name":"camera.getOptions",
  "parameters": {
      "optionNames": [
          "photoStitchingSupport",
          "photoStitching"
      ]
  }
}

如果相机支持机内拼接，则会正确返回如下结果，此时可根据您的业务需求选择是否使用此功能。如果返回错误结果或photoStitchingSupport返回只有none，则代表相机不支持机内拼接功能

{
  "results": {
      "options": {
           "photoStitchingSupport":["none","ondevice"],
           "photoStitching":"none"
      }
  }
}
字段说明
iso当前 iso 值
isoSupport列出所有支持的 iso 值
shutterSpeed快门
shutterSpeedSupport所支持的快门值
hdrSupport列出 HDR 选项
hdr显示当前 HDR 设置值
totalSpace内存卡总容量(Byte)
remainingSpace剩余存储容量(Byte)
photoStitchingSupport列出机内拼接选项
photoStitching显示当前机内拼接设置值
captureInterval间隔拍照时间
captureIntervalSupport间隔拍照支持的时间范围
captureMode拍摄模式
_videoType视频子模式
_videoTypeSupport视频子模式列表
_timelapseResolution延时摄影分辨率
_timelapseResolutionSupport可用的延时摄影分辨率列表
_timelapseInterval延时摄影的间隔时间,单位为毫秒
_timelapseIntervalSupport可用延时摄影的时间列表
exposureProgram曝光模式:1 手动 Manual,2 自动 NormalProgram,4 快门优先 ShutterPriority,9 ISO 优先 ISOPriority
exposureDelay曝光延迟时间,启动拍摄后延迟一定时间再曝光
exposureDelaySupport列出支持的曝光延迟时间
_topBottomCorrection照片水平校正开关
whiteBalance当前白平衡的模式名称
whiteBalanceSupport列出支持的白平衡设置值
_dateTime时间格式 "YYYY:MM:DD HH:MM:SS",例如 "2022:05:06 17:56:15"
_MuteEnable静音设置,0 为不静音,1 为静音
_batteryCapacitypowerType 充电状态(0 未充电,1 正在充电);powerLevel 电量百分比(100 表示 100%,0 表示没电池)
_sysTimestamp系统时间戳,单位为 us

无需每次请求都附带所有项目,根据需要选择即可。

拍照 ​

setOptions ​

  • 使用camera.setOptions 设置参数

  • 拍摄HDR照片（拍摄完成后会有三张双鱼眼图片，需要在app中进行HDR合成和全景拼接）

{
	"name": "camera.setOptions",
	"parameters": {
		"options": {
			"captureMode":"image",
			"hdr": "hdr",
			"photoStitching": "none" //如果相机不支持机内拼接功能，请不要添加此参数
		}
	}
}
  • 拍摄机内拼接 HDR照片命令如下：（拍摄完成后会返回一张进行过HDR合成及拼接的全景图片）
{
	"name": "camera.setOptions",
	"parameters": {
		"options": {
			"captureMode":"image",
			"hdr": "hdr",
			"photoStitching": "ondevice"  //如果相机不支持机内拼接功能，请不要添加此参数
		}
	}
}

正确返回：

{
    “name”:"camera.setOptions",
    "state":"done"
}

参数错误返回:

{
    "error": {
        "code": "invalidParameterName",
        "message": "Parameter options contains unsupported option captureInterval."
    }
}

takePicture ​

  • 使用 camera.takePicture 拍摄照片
{
    "name":"camera.takePicture"
}

拍摄成功正确：

{
    "name":"camera.takePicture",
    "state":"inProgress",
    "id":"001996",
    "progress":
    {
        "completion":0
    }
}

拍摄失败--相机未激活，遇到此报错时，需要提示用户下载Insta360官方app激活 :

{
	"name": "camera.takePicture",
	"state": "error",
	"error": {
		"code": "unactivated",
		"message": "Please activate your camera in insta360 official app."
	}
}

拍摄失败-状态错误，遇到此报错时，相机可能进入了Standby模式或者视频模式，重新发送setOption即可激活：

{
	"name": "camera.takePicture",
	"state": "error",
	"error": {
		"code": "disabledCommand",
		"message": "Currently camera is not working in image mode"
	}
}

查询status ​

  • 使用 /osc/commands/status 查询当前命令的执行进度
{
    "id": "001996"
}

返回 id 为 001996 的拍摄命令执行进度：

{
    "name":"camera.takePicture",
    "state":"inProgress",
    "id":"001996",
    "progress":
    {
        "completion":0.5
    }
}

completion 0.5 表示进度为50%

获取地址并下载 ​

  • 重复查询 /osc/commands/status 直到 state 为 done 使用 results 结果中的 fileUrl 来下载文件
{
	"name": "camera.takePicture",
	"state": "done",
	"results": {
		"_fileGroup": ["http://192.168.42.1:80/DCIM/Camera01/IMG_20180101_051113_00_042.jpg"],
		"_localFileGroup": ["/DCIM/Camera01/IMG_20180101_051113_00_042.jpg"],
		"fileUrl": "http://192.168.42.1:80/DCIM/Camera01/IMG_20180101_051113_00_042.jpg"
	}
}

删除照片(optional) ​

  • 通过 camera.delete 删除文件
{
    "name":"camera.delete",
    "parameters": {
        "fileUrls": [
            "url1",
            "url2",
            "url3",
            ...
            "urln"
        ]
    }
}

正确返回：

{
	"name": "camera.delete",
	"results": {
		"fileUrls": []
	},
	"state": "done"
}

错误返回:

{
    "error": {
        "code": "invalidParameterValue",
        "message": "Parameter url3 doesn't exist."
    }
}

获取照片文件列表 ​

  • 使用camera.listFiles列出照片列表
{
	"name": "camera.listFiles",
	"parameters": {
		"fileType": "image",
		"entryCount": 1,
		"maxThumbSize": 100
	}
}
{
	"name": "camera.listFiles",
	"state": "done",
	"results": {
		"entries": [{
			"name": "IMG_20180106_180200_00_006.jpg",
			"fileUrl": "http://192.168.42.1:80/DCIM/Camera01/IMG_20180106_180200_00_006.jpg",
			"_localFileUrl": "/DCIM/Camera01/IMG_20180106_180200_00_006.jpg",
			"size": 4494224,
			"width": 6080,
			"height": 3040,
			"dateTimeZone": "2018:01:06 18:02:14+08:00",
			"_thumbnailSize": 37312,
			"isProcessed": true,
			"previewUrl": "",
			"thumbnail": "/9j/2wCEAAI...2Q==\n"//...表示省略
		}],
		"totalEntries": 3
	}
}

录像 ​

setOptions ​

  • 设置captureMode为video模式
json
{
	"name": "camera.setOptions",
	"parameters": {
		"options": {
			"captureMode":"video"
		}
	}
}

正确返回：

{
	"name": "camera.setOptions",
	"state": "done"
}

startCapture ​

  • 使用camera.startCapture开始录制视频
{
    "name":"camera.startCapture"
}

stopCapture ​

  • 使用camera.stopCapture停止录制
{
    "name":"camera.stopCapture"
}

正确返回结果如下，其中包含fileUrls可以用来下载视频：

{
	"name": "camera.stopCapture",
	"state": "done",
	"results": {
		"fileUrls": [
			"http://192.168.42.1:80/DCIM/Camera01/VID_20180106_172302_10_005.mp4",
			"http://192.168.42.1:80/DCIM/Camera01/VID_20180106_172302_00_005.mp4"
		],
		"_localFileUrls": [
			"/DCIM/Camera01/VID_20180106_172302_10_005.mp4",
			"/DCIM/Camera01/VID_20180106_172302_00_005.mp4"
		]
	}
}

startTimelapse ​

  1. timelapse拍照之前需要设置timelapse模式
{
    "name":"camera.setOptions",
    "parameters":{
        "options":{
            "captureMode":"video",
            "_videoType":"timelapse",
            "_timelapseInterval":1
        }
    }
}
  1. 开始拍摄
{
    "name":"camera.startCapture"
}

stopTimelapse ​

  • 使用camera.stopCapture停止录制
{
    "name":"camera.stopCapture"
}

正确返回结果如下，其中包含fileUrls可以用来下载视频：

{
	"name": "camera.stopCapture",
	"state": "done",
	"results": {
		"fileUrls": [
			"http://192.168.42.1:80/DCIM/Camera01/VID_20180106_172302_10_005.mp4",
			"http://192.168.42.1:80/DCIM/Camera01/VID_20180106_172302_00_005.mp4"
		],
		"_localFileUrls": [
			"/DCIM/Camera01/VID_20180106_172302_10_005.mp4",
			"/DCIM/Camera01/VID_20180106_172302_00_005.mp4"
		]
	}
}