controlPTZ (controlPTZ: PTZ control)

controlPTZ: controlPTZ: PTZ control

Legacy HTTP retained: New integrations can use PTZ relative move (device.service.invoke) for the related capability. The two interfaces are not a one-to-one replacement. No registry one-to-one registration of this old method.

Function details

Control pan, tilt, and zoom for a device channel.

Note: The device must support PTZ-related capabilities. See Device capability set.

Request address

https://openapi-[DataCenter].easy4ip.com/openapi/controlPTZ

Request format

HTTP POST. JSON body layout: Request conventions. Sign with Signature.

Incoming parameter description

Parameter name	Parameter type	Required or not	Legal value	Parameter description
token	String	Yes		Administrator accessToken
deviceId	String	Yes		Device serial number
channelId	String	Yes		Channel number
operation	String	Yes	`move`, `locate`	`move`: continuous move; `locate`: absolute position
h	Double	Yes	`move`: [-8,8]; `locate`: [-1,1]	Horizontal parameter
v	Double	Yes	`move`: [-8,8]; `locate`: [-1,1]	Vertical parameter
z	Double	Yes	`move`: unrestricted; `locate`: [0,1]	Zoom parameter
duration	String	No	`last` or milliseconds	For `move` only: duration in ms; omit or `last` to keep moving

Note: TP1 models do not support negative vertical angles; when device model is TP1, v must not be negative.

Sample input

{
 "system":{
 "ver":"1.0",
 "appId":"lcdxxxxxxxxx",
 "sign": "xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=",
 "time":1599027466,
 "nonce":"44299852-e827-46c0-8feb-f373dde79083"
 },
 "id":"21893dda-17b6-418d-9178-e05f31ae79ec",
 "params":{
 "duration":"2000",
 "v":"4",
 "h":"4",
 "z":"1",
 "deviceId":"TESTQWERXXXX",
 "operation":"move",
 "channelId":"0",
 "token":"At_00006ac6e32d123141238f60147de7ec"
 }
}

operation is move or locate; do not mix both in one session.
move (continuous): h/v speed in [-8,8] (negative left/down, positive right/up); z zoom factor unrestricted. h=0,v=0,z=1 stops immediately. duration is milliseconds; omit or use last to move until stopped.
locate (absolute): h and v in [-1,1]; z normalized [0,1] (0=min zoom, 1=max). duration is ignored.

Return data field description

No data payload on success.

Sample output

{
	"id":"21893dda-17b6-418d-9178-e05f31ae79ec",
	"result":{
		"code":"0",
		"msg":" Operation is successful."
	}
}

Error codes

This method may return the codes below. See Return codes and Capability errors for the full catalog.

Gateway and auth (SN / TK / OP)

Code	Meaning	Next step
`SN1001`	Signature error	Check `sign` per Development specification
`TK1002`	Token invalid or expired	Refresh accessToken
`OP1002`	Missing required parameter	Add required fields
`OP1003`	Invalid parameter	Match this page’s parameter table
`OP1009`	Permission denied	Check token and device bind/share grants
`OP1013`	Total call limit exceeded	Reduce call rate
`OP1014`	Daily per-interface limit exceeded	See Interface call limits
`DV1007`	Device offline	Wait until the device is online

See Return codes · OP/SN/TK for the full catalog.

Sub-accounts (SUB)

Code	Meaning	Next step
`SUB1001`–`SUB1002`	Sub-account lacks API permission	Update policy via addPolicy
`SUB1005`	Sub-account token expired	Refresh subAccountToken
`SUB1006`	No device grant for sub-account	Check `Resource` and device serial
`SUB1008`	Sub-account not bound to app	Create and bind the sub-account first

See Return codes · SUB.

Device access and channels (DV10xx)

Code	Meaning	Next step
`DV1007`	Device offline or timeout	Wait for the device to come online
`DV1009`	Device busy	Retry later
`DV1012`	Insufficient share/grant permission	Check sub-account `Permission` / `Resource`
`DV1019`	Capability not supported	Confirm model and capability list
`DV1020`	Channel offline	Check channel status
`DV1026`	Function not supported	Use another API or upgrade firmware
`DV1028`	Not bound or channel missing	Verify `deviceId` / `channelId`

See Return codes · DV.

Presets and PTZ (DV10xx)

Code	Meaning	Next step
`COLLECTION_OUT_LIMIT`	Collection point limit reached	Delete an existing point
:---	:---	:---
`COLLECTION_EXIST`	Collection name already exists	Use another name

See Return codes · catalog.