Execute a single PTZ (Pan-Tilt-Zoom) command on an camera that belongs to the organization
associated with the API key. One endpoint drives every action: set action to the numeric PTZ
command and pass the matching parameters under meta.
The command is dispatched asynchronously to the edge device; the response is held open until the
edge replies (up to 15 seconds). Successful responses return {} for ack-only actions, or PTZ
fields (status, presets, preset, test) for actions that produce payload data.
Axis ranges: pan/tilt are normalized to [-1, 1]; zoom velocity/delta are signed [-1, 1]; zoom
absolute position is [0, 1]. PresetToken is HOME or a numbered token 1..10.
action → required meta (a mismatch returns HTTP 400 with a per-action reason):
| action | name | meta |
|---|---|---|
| 0 | PtzMove | { speed:{x,y,z}, timeout, zoomTimeout? } |
| 1 | GotoHomePosition | — |
| 2 | SetHomePosition | — |
| 3 | GetStatus | — (returns status) |
| 4 | PtzStop | — |
| 5 | ContinuousMove | { Velocity:{x,y,z}, Timeout } |
| 6 | AbsoluteMove | { Position:{x,y,z}, Speed:{x,y,z} } |
| 7 | RelativeMove | { Translation:{x,y,z}, Speed:{x,y,z} } |
| 8 | StopMove | { PanTilt:boolean, Zoom:boolean } |
| 9 | SetPreset | { PresetToken, PresetName } |
| 10 | GetPresets | — (returns presets) |
| 11 | GotoPreset | { PresetToken, Speed?:{x,y,z} } |
| 12 | RemovePreset | { PresetToken } |
| 13 | PtzTest | — (non-destructive probe, returns test) |
driver is an optional override (Onvif=0, Vivotek=1, Uniview=2, Vivotek2=3, Axis=4, Hanwha=5).
Omit it to let the edge resolve the driver automatically. Not every brand supports every action —
HTTP 501 is the expected response for unsupported operations (e.g. absolute move on Hanwha); run
PtzTest first to discover per-camera capabilities.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Invalid request. The meta does not match the action.
Missing or invalid API key.
Organization not allowed by this token.
Camera not found in the organization.
Request timed out waiting for the edge device response.
Internal server error.
PTZ command not supported by the camera.
Camera unreachable from the edge device.