Overlay API

The Overlay API is used to access overlay functionality such as privacy masks, text overlay and image overlay. The API is divided into:

• Dynamic overlay API
• Overlay modifiers
• Privacy mask API
• Text overlay API
• Overlay image API
• Image overlay API (Old version)

Dynamic overlay API

Description

Dynamic overlay is used to configure different sorts of overlays in the Axis cameras and improves on the previously used param.cgi-based API by also being able to:

• Have more than one text or image overlay.
• Place text overlay other than on the top or bottom of the image.
• Have multiple lines for the text overlay.

The Dynamic overlay API gives applications and users the ability to both get and set overlay configurations in the Axis cameras. Each overlay in the camera is identified by an ID which is returned upon creation. An overlay can be either text, image or special overlays that are provided by other applications, such as the Privacy mask API. It is also possible to remove overlays created by the API. The special overlays can not be configured from this API.

Function	Description
dynamicoverlay.cgi	CGI holding all methods needed to add, change, remove and list overlays. Requests and responses are in the JSON format.

Method	Description
addImage	Creates an image overlay and returns an overlay ID if successful, otherwise returns an error.
addText	Creates a text overlay and returns an overlay ID if successful, otherwise returns an error.
getSupportedVersions	Get the available API versions.
list	Get a summary of all overlays created.
remove	Remove the overlay identified by a specific overlay ID.
setImage	Change properties of a specific image overlay identified by an specified overlay ID.
setText	Change properties of a specific text overlay identified by a specified overlay ID.
getOverlayCapabilities	Returns the number of the total overlay slots, number of slots occupied per text overlay and the number of occupied slots per image overlay.

Overview

Model

The API consists of a CGI enabling a user to control the underlaying dynamic overlays. There is one CGI request that implements a number of methods and to which the responses are in the JSON format.

The CGI gives the client the ability to:

• Create image overlays.
• Create text overlays.
• Alter properties on a previously created overlay.
• Remove a given overlay.
• List created overlays.
• Request a list with the supported API versions.

Note:

• All of the overlays, especially those that are neither text nor image overlays, can be modified by internal applications.
• The coordinate system used in this API is [-1.0,1.0] for both the X and Y axis. In addition to the coordinate system there are also several named positions, such as topLeft.
• The maximum number of characters for each individual text overlay is 512.

Identification

• Property: Properties.API.HTTP.Version=3
• Property: Properties.DynamicOverlay.DynamicOverlay=yes
• Property: Properties.DynamicOverlay.Version=1.00
• Firmware: 7.10 and later

Obsolestes

The Dynamic overlay API replaces the previously used Image overlay and Text overlay API that were both using the param.cgi parameter.

Limitations

The implementation uses the same resources as param.cgi. It is possible to use dynamicoverlay.cgi to change overlays created with param.cgi and vice versa. However, using both dynamicoverlay.cgi and param.cgi for overlay handling may lead to unexpected behavior.

Overlay IDs may change after a reboot. This is because the overlay system always uses the lowest available number, starting from 1.

Common examples

How to use the examples

The examples in the following sections are formatted to be used with cURL.

curl --anyauth -H "Content-Type: application/json" --data @sample_code.json https://$ip/axis-cgi/dynamicoverlay/dynamicoverlay.cgi

Add text overlays

Use this example to add text overlays with transparent backgrounds, in this case one at the top left corner of the video that shows timestamps and another at the right bottom corner that shows the address and location of the camera.

1. Add a text overlay at the top left corner that shows the timestamp. If the font size is not specified by the user a suitable font size will be selected by the camera depending on resolution. The font size will then have to be read back with a list command should the user require it.

{
  "apiVersion": "1.0",
  "context": "321",
  "method": "addText",
  "params": {
    "camera": 1,
    "text": "%c",
    "position": "topLeft",
    "textColor": "white"
  }
}

2. Parse the JSON response.

a. Success response example. The response returns the identity of the overlay created.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "321",
  "data": {
    "camera": 1,
    "identity": 0
  }
}

b. Failure response example.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "321",
  "error": {
    "code": 304,
    "message": "Invalid value for parameter text"
  }
}

3. Add a text overlay at the bottom right corner that shows the address using a specified font size.

{
  "apiVersion": "1.0",
  "context": "456",
  "method": "addText",
  "params": {
    "camera": 1,
    "text": "Emdalav/u00E4gen 14\nLund",
    "position": "bottomRight",
    "fontSize": 14,
    "textColor": "white"
  }
}

4. Parse the JSON response.

a. Success response example. The response returns the identity of the overlay created.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "456",
  "data": {
    "camera": 1,
    "identity": 1
  }
}

b. Failure response example.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "456",
  "error": {
    "code": 300,
    "message": "Unable to create overlays (limit reached)"
  }
}

API references:

addText

Add image overlays

Use this example to add an image overlay at the left bottom corner of the video.

General preparations

Upload an image to the camera according to Upload a new image.

An overlay can contain several bitmap images to be adaptable to different resolutions. By calling the list command, the user receives a list showing all of the available pictures.

The user may then call the addImage command to create an image overlay. The overlays present are:

/etc/overlays/axis(128x44).ovl
/etc/overlays/image.ovl

where /etc/overlays/axis(128x44).ovl comes pre-installed.

By calling the list command a second time, the user receives information on all of the overlays, including the newly created overlay. In the description of the overlay is a variable called scalable that let the user know if the overlay is scale-to-resolution or not. Scale-to-resolution means that the image overlay re-scale based on the resolution of the video stream.

1. Add an image overlay at the default location with a company logo.

{
  "apiVersion": "1.0",
  "context": "789",
  "method": "addImage",
  "params": {
    "camera": 1,
    "overlayPath": "image.ovl"
  }
}

2. Parse the JSON response.

a. Success response example. The response returns the identity of the overlay created.

{
  "apiVersion": "1.0",
  "method": "addImage",
  "context": "789",
  "data": {
    "camera": 1,
    "identity": 2
  }
}

b. Failure response, see Error handling

API references

addImage

List overlays

Use this example to retrieve a list of all overlays used in a device.

1. List all overlays previously created by add methods.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "list",
  "params": {
  }
}

2. Parse the JSON response.

a. Success respons example. The response gives a list of overlays with all corresponding properties. Note that scale-to-resolution overlays are only listed as a single directory as described in Add image overlays for the add image overlay usecase. If the overlay is scaled to the resolution, then the scalable property should be set to true.

{
  "apiVersion": "1.0",
  "data": {
    "imageFiles": [
      "/etc/overlays/axis(128x44).ovl",
      "/etc/overlays/logo.ovl"
    ],
  "imageOverlays": [
    { "camera": 1, "identity": 2, "overlayPath": "logo.ovl", "position": ... },
    ...
  ],
  "textOverlays": [
    { "camera": 1, "identity": 0, ... "text": ... "fontSize": 80, "size": [32, 48]},
    { "camera": 1, "identity": 1, ... "text": ... "fontSize": 14, "size": [47, 256]},
    ...
    ]
  },
  "method": "list",
}

b. Failure response, see Error handling

API references:

list

Update overlays

Use this example to

Set text overlay

1. Set text color to white and background to red.

{
  "apiVersion": "1.0",
  "context": "456",
  "method": "setText",
  "params": {
    "identity": 0,
    "textBGColor": "red"
  }
}

2. Parse the JSON response.

a. Success response example.

{
  "apiVersion": "1.0",
  "method": "setText",
  "data": {}
}

b. Failure response, see Error handling

API references:

setText

Set image overlay

1. Update image overlay

Update overlay image.

{
  "apiVersion": "1.0",
  "context": "333",
  "method": "setImage",
  "params": {
    "identity": 2,
    "camera": 1,
    "overlayPath": "redlogo.ovl"
  }
}

2. Parse the JSON response.

a. Success response example.

{
  "apiVersion": "1.0",
  "method": "setImage",
  "context": "333",
  "data": {}
}

b. Failure response, see Error handling

API references:

setImage

Remove overlays

Use this example to remove an overlay based on its ID.

1. Remove the overlay with a specified identity.

{
  "apiVersion": "1.0",
  "context": "444",
  "method": "remove",
  "params": {
    "identity": 1
  }
}

2. Parse the JSON response.

a. Success response example.

{
  "apiVersion": "1.0",
  "method": "remove",
  "context": "444",
  "data": {}
}

b. Failure response, see Error handling.

API references:

remove

getSupportedVersions

Use this example to check if features are supported before an application uses them.

1. Get a list of supported JSON API versions. Note that no apiVersion is supposed to be defined in the request.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getSupportedVersions"
}

2. Parse the JSON response to find out whether the operation was successful or not.

a. Success response example.

{
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": [
      {"1.0"},
      {"2.0"},
      {"3.0"},
    ]
  }
}

b. Failure response, see Error handling

API references:

getSupportedVersions

Get the maximum number of overlays

Use this example to receive information about how many overlays that can be used.

1. Get the overlay capabilities for this camera.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getOverlayCapabilities"
}

2. Parse the JSON response to find out whether the operation was successful or not.

a. Success response example.

{
  "method": "getOverlayCapabilities",
  "context": 123,
  "apiVersion": "1.0",
  "data": {
    "numberAvailbleSlots": 8,
    "slotsPerImageOverlay": 2,
    "slotsPerTextOverlay": 1
  }
}

b. Failure response, see Error handling

API references:

getOverlayCapabilities

Add overlay with scrolling text

note

This feature has been deprecated as of AXIS OS version 11.10 and will no longer receive any updates.

Use this example to implement an overlay with scrolling text when the text gets to long to fit in the video stream.

1. Create a text overlay at the bottom, then specify a background color to make the text easier to read. Set the scroll speed to negative to make the text move from right to left.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "addText",
  "params": {
    "camera": 1,
    "text": "Weather forecast: Sunny every day! --- Stock index OMSX +0.3%, ...",
    "scrollSpeed": -1,
    "position": "bottomRight",
    "textColor": "white",
    "textBGColor": "black"
  }
}

2. Parse the JSON response to find out whether the operation was successful or not.

a. Success response example.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "123",
  "data": {
    "camera": 1,
    "identity": 1
  }
}

b. Failure response example.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "123",
  "error": {
    "code": 310,
    "message": "Invalid value for parameter scroll speed"
  }
}

API references:

addText

API documentation

Key:

• ?

  Indicates zero or one occurrences

• +

  Indicates one or more occurrences

All existing properties and values of the current text and image overlays from param.cgi will be supported with only changes as follows:

1. textColor can also be "red"

2. %0A can be put in text as a new line to make multi-line string.

3. One new property, textOLColor is added for text overlays, possible values are "black", "white", "red", "transparent" and semiTransparent".

addText

addText is used to create new text overlays. When creating an overlay using the CGI you may also specify properties at the same time.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "addText",
  "params": {
    "camera": <1-x>,
    "text": <string>
    "position": <top | topRight | bottomRight | bottom | bottomLeft | topleft> | [decimal,decimal],
    "fontSize": <0-200>,
    "scrollSpeed": <(-20)-20>,
    "textColor": <black | white | red | transparent | semiTransparent>,
    "textBGColor": <black | white | red | transparent | semiTransparent>,
    "textOLColor": <black | white | red | transparent | semiTransparent>,
    "reference": <channel | scene>,
    "ptPosition": <(-180)-180>,
    "zoomInterval": <1-19999>,
    "indicator": <string>,
    "indicatorSize": <0-200>,
    "indicatorColor": <black | white | red | transparent | semiTransparent>,
    "indicatorBG": <black | white | red | transparent | semiTransparent>,
    "indicatorOL": <black | white | red | transparent | semiTransparent>
  }
}

• apiVersion The API version that the response should use.
• method="addText" Specifies that the addText operation is performed.
• context=<string> Optional. The user sets this value and server echoes the data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
• camera=<1-x> Required. Defines the view area on which the overall shall be displayed on. "x" is the number of available view areas on the product and can be found in Plain Config/Image/Nbr of configs.
• text=<string> Required. Defines text to be displayed.
• position=<top | topRight | bottomRight | bottom | bottomLeft | topLeft> | [decimal,decimal] Optional. Defines the x, y coordinates to place the overlay either by predefined strings or a relative x, y position consisting of an array of two numbers from -1.0 up to 1.0. Default is 0.0,0,0.
• textColor=<black | white | red | transparent | semiTransparent> Optional. Defines which color the text is displayed in. Default is black.
• textBGColor=<black | white | red | transparent | semiTransparent> Optional. Defines which background color to display. Default is transparent.
• textOLColor=<black | white | red | transparent | semiTransparent> Optional. Defines which outline color to display. Default is transparent.
• fontSize=<0-200> Optional. Defines the size of the text. Default size is determined relative to the maximal camera resolution, use "list" to get the actual size.
• reference=<channel | scene> Optional. Defines how the position coordinates are expressed. Default value is channel.
• When channel is the reference, the specified coordinates are relative to the video as it is seed by a user.
• When scene is the reference, the overlay position consists of normalized pixel coordinate, like with channel. Pan and tilt values for the PTZ along with a zoom interval can also be used to define the overlay, while the pixel coordinates defines the position of the overlay in the camera image. The PTZ coordinates defines the pan and tilt position in degrees, where the overlay is places in the scene. The zoom interval determines between which zoom values the overlay will be visible.
• ptPosition=<(-180)-180> | [integer, integer] Optional. The pan/tilt coordinates of the PTZ, measured in degrees. Defines at which PTZ position an overlay is visible on the camera image. The coordinates should be given as an array of two integers between -180 to 180. The default pan and tilt values reflects the position of the camera from when the overlay was created.
• zoomInternval=<1-19999> | [integer, integer] Optional.
• scrollSpeed=<(-20)-20> Optional. This property is used to make the text slide across the stream instead of being stationary. Positive values cause the text to slide from left to right while negative values cause it to slide from right to left. When the text has fully left the stream it reappears on the other side. The default is 0. If textBGColor also is set the background will cover the whole width of the stream rather than only where the text is currently located.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": <string>,
  "data": {
    "camera": <integer>,
    "identity": <integer>
  }
}

• apiVersion Current version is 1.0.
• method="addText" The method described in this section.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.
• data.camera The view area on which the overlay was created.
• data.identity The identity of the overlay created.

Return value - Failure

See Error handling

Error codes

The following table lists error codes that can be returned from this method. General errors are listed in Error handling.

Code	Description
300	Unable to create overlays (limit reached).
301	Invalid value for parameter camera.
303	Invalid value for parameter position.
304	Invalid value for parameter text.
306	Invalid value for parameter textColor.
307	Invalid value for parameter textBGColor.
308	Invalid value for parameter textOLColor.
309	Invalid value for parameter fontSize.
310	Invalid value for parameter scrollSpeed.

addImage

addImage is used to create new image overlays. When creating an overlay using the CGI you may also specify properties at the same time.

Refer to the Overlay API section on uploading images for instruction on how to upload new images.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "addImage",
  "params": {
    "camera": <1-x>,
    "overlayPath": <string>,
    "position": <top | topRight | bottomRight | bottom | bottomLeft | topLeft> | [decimal,decimal]
  }
}

• apiVersion The API version that the response should use.
• method="addImage" Specifies that the addImage operation is performed.
• context=<string> Optional. Client sets this value and server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
• camera=<1-x> Required. Defines the view area on which the overlay shall be displayed on. x is the number of available view areas on the product and can be found in Plain Config/Image/Nbr of configs.
• overlayPath=<string> Required. Defines path to image to display. Default is an empty string.
• position=<top | topRight | bottomRight | bottom | bottomLeft | topLeft> | [decimal,decimal] Optional. Defines the x,y coordinates to place the overlay either by predefined strings or a relative x,y position consisting of an array of two numbers from -1.0 up to 1.0. Default is 0.0,0.0.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "1.0",
  "method": "addImage",
  "context:" <string>,
  "data": {
    "camera": <integer>,
    "identity": <integer>
  }
}

• apiVersion Current version is 1.0.
• method="addImage" The method described in this section.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.
• data.camera The view area on which the overlay was created.
• data.identity The identity of the overlay created.

Return value - Failure

See Error handling

Error codes

The following table lists error codes that can be returned from this method. General errors are listed in Error handling.

Code	Description
300	Unable to create overlays (limit reached).
301	Invalid value for parameter camera.
303	Invalid value for parameter position.
305	Invalid value for parameter overlayPath

setText

setText is used to update parameters for a certain text overlay. The user may specify more than one parameter at any time. Optional parameters that are not supplied will not be charged.

Request

• Security level: Operator
• Method: POST

Response body syntax

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "setText",
  "params": {
    "identity": <integer>,
    "text": <string>,
    "position": <top | topRight | bottomRight | bottom | bottomLeft | topLeft> | [decimal,decimal],
    "fontSize": <0-200>,
    "scrollSpeed": <(-20)-20>,
    "textColor": <black | white | red | transparent | semiTransparent>,
    "textBGColor": <black | white | red | transparent | semiTransparent>,
    "textOLColor": <black | white | red | transparent | semiTransparent>
  }
}

• apiVersion The API version that the response should use.
• method="setText" Specifies that the setText operation is performed.
• context=<string> Optional. Client sets this value and server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
• identity=<integer> Required. Defines which overlay to change.
• text=<string> Optional. Defines the text to be displayed.
• position=<top | topRight | bottomRight | bottom | bottomLeft | topLeft> Optional. Defines the x, y coordinates to place the overlay either by predefined strings or a relative x, y position consisting of an array of two numbers from -1.0 up to 1.0. Default is 0.0,0.0.
• textColor=<black | white | red | transparent | semiTransparent> Optional. Defines which color the text is displayed in.
• textBGColor=<black | white | red | transparent | semiTransparent> Optional. Defines which background color to display.
• textOLColor=<black | white | red | transparent | semiTransparent> Optional. Defines which outline color to display.
• fontSize=<0-200> Optional. Defines the size of the text.
• scrollSpeed=<(-20)-20> Defines the speed by which the text slides across the stream.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "1.0",
  "method": "setText",
  "context": <string>,
  "data": {}
}

• apiVersion Current version is 1.0.
• method="setText" The method described in this section.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.

Successful calls contains an empty data object.

Return value - Failure

See Error handling

Error codes

The following table lists error codes that can be returned from this method. General errors are listed in Error handling.

Code	Description
302	Invalid value for parameter identity.
303	Invalid value for parameter position.
304	Invalid value for parameter text.
306	Invalid value for parameter textColor.
307	Invalid value for parameter textBGColor.
308	Invalid value for parameter textOLColor.
309	Invalid value for parameter fontSize.
310	Invalid value for parameter scrollSpeed.

setImage

setImage is used to update parameters for a certain image overlay. The user may specify more than one parameter at one time, however optional parameters that are not supplied will not be changed.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion". <string>,
  "context": <string>,
  "method": "setImage",
  "params": {
    "identity": <integer>
    "overlayPath": <string>
    "position": <top | topRight | bottomRight | bottom | bottomLeft | topLeft> | [decimal,decimal]
  }
}

• apiVersion The API version that the response should use.
• method="setImage" Specifies that the setImage operation is performed.
• context=<string> Optional. Client sets this value and server echoes data in response. If set, it will be present in the response regardless of whether the response is successful or an error.
• identity=<integer> Required. Defines which overlay to change.
• overlayPath=<string> Optional. Defines path to image to display.
• position=<top | topRight | bottomRight | bottom | bottomLeft | topLeft> | [decimal,decimal] Optional. Defines the x, y coordinates to place the overlay either by predefined strings or a relative x, y position consisting of an array of two numbers from -1.0 up to 1.0. Default is 0.0,0.0.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "1.0",
  "method": "setImage",
  "context": <string>,
  "data": {}
}

• apiVersion Current version is 1.0.
• method="setImage" The method described in this section.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.

Successful calls contains an empty data object.

Return value-Failure

See Error handling.

Error codes

The following table lists error codes that can be returned from this method. General errors are listed in Error handling.

Code	Description
302	Invalid value for parameter identity.
303	Invalid value for parameter position.
305	Invalid value for parameter overlayPath.

list

list all overlays created by the add CGIs and display both their IDs and other properties. If specified, properties for all overlays can be listed for a given camera or, if further specified, for a specific camera layer. The IDs may change for each overlay after a reboot. It is therefore recommended to check the current overlay ID with list before it is updated or removed.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "list",
  "params": {
    "camera": <1-x>,
    "identity": <integer>
  }
}

• apiVersion The API version that the response should use.
• method="list" Specifies that the list operation is performed.
• context=<string> Optional. Client sets this value and the server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
• camera=<1-x> Optional. Defines which view area we want to list properties for. Supplied either by the add or list CGIs. If not specified all view areas are listed.
• identity=<integer> Optional. Defines which specific overlay to list properties for.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "1.0",
  "method": "list",
  "context": <string>
  "data": {
    "imageFiles": ["fileName", "fileName"],
    "imageOverlays": [
      {
        "camera": <integer>,
        "identity": <integer>,
        "overlayPath": <string>,
        "position": [<decimal>,<decimal>] | <string>,
        "zIndex": <integer>,
        "visible": <boolean>
        "scalable": <boolean>
      }
    ],
    "textOverlays": [
      {
        "camera": <integer>,
        "identity": <integer>,
        "position": [<decimal>,<decimal>] | <string>,
        "text": <string>,
        "textColor": <string>,
        "textBGColor": <string>,
        "textOLColor": <string>,
        "fontSize": <integer>
        "scrollSpeed": <integer>,
        "size": [<integer>,<integer>],
        "zIndex": <integer>,
        "visible": <boolean>
        "scalable": <boolean>
      }
    ]
  }
}

• apiVersion Current version is 1.0.
• method="list" The method described in this section.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.
• data.imageFiles[]=<list of image overlay files> List of file names available to use as image overlays, for example ["/etc/overlays/image1.ovl", "/etc/overlay/image2.ovl"]
• data.imageOverlays[].camera The view area.
• data.imageOverlays[].identity The overall identity.
• data.imageOverlays[].position The textual position string or x, y coordinates where the overlay is located.
• data.imageOverlays[].overlayPath The path to the image used for the overlay.
• data.imageOverlays[].zIndex If zIndex of the overlay.
• data.imageOverlays[].visible If the overlay is visible.
• data.imageOverlays[].scalable If the overlay is scaled, based on the resolution.
• data.textOverlays[].camera The view area.
• data.textOverlays[].identity The overlay identity.
• data.textOverlays[].position The textual position string or x, y coordinate where the overlay is located.
• data.textOverlays[].text The overlay text.
• data.textOverlays[].textColor The text color for the overlay.
• data.textOverlay[].textBGColor The background color for the overlay.
• data.textOverlay[].textOLColor The outline color for the overlay.
• data.textOverlay[].fontSize The outline color for the overlay.
• data.textOverlays[].scrollSpeed The scroll speed for the overlay.
• data.textOverlays[].size The actual size in pixels of the text overlay.
• data.textOverlays[].zIndex If zIndex of the overlay.
• data.textOverlays[].visible If the overlay is visible.
• data.textOverlays[].scalable If the overlay is scaled, based on the resolution.

Return value - Failure

See Error handling.

Error codes

The following table lists error codes that can be returned form this method. General errors are listed in Error handling.

Code	Description
301	Invalid value for parameter camera.
302	Invalid value for parameter identity.

remove

remove will delete the overlay identified by the provided id.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "<remove>",
  "params": {
    "identity": <integer>
  }
}

• apiVersion The API version that the response should use.
• method="list" Specifies that the +remove+1 operation is performed.
• context=<string> Optional. User sets this value and the server echoes the data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
• identity=<integer> Required. Defines which overlay to remove. Supplied either by the add or list CGIs.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "1.0",
  "method": "remove",
  "context": <string>,
  "data": {}
}

• apiVersion Current version is 1.0.
• method="remove" The method described in this section.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.

All successful calls contains an empty data object.

Return value - Failure

See Error handling.

Error codes

The following table lists error codes that can be returned from this method. General errors are listed under Error handling.

Code	Description
301	Invalid value for parameter camera.
302	Invalid value for parameter identity.

getSupportedVersions

getSupportedVersions is used to retrieve the list of supported response schema versions that are available.

Request

• Security level: Operator
• Method: POST

{
  "context": <string>,
  "method": "getSupportedVersions"
}

• method="getSupportedVersions" Specifies that the getSupportedVersions operation is performed.
• context=<string> Optional. Client sets this value and server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "method": "getSupportedVersions",
  "context": <string>,
  "data": {
    "apiVersions": ["<Major1>.<Minor1>", "<Major2>.<Minor2>"]
  }
}

• method="getSupportedVersions" The method described in this section.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.
• data.apiVersions[]=<list of versions> List of supported versions, all major versions with highest supported minor version.
• <list of versions> List of "<Major>.<Minor>" versions e.g. ["1.4", "2.5"].

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "method": "The called method",
  "context": "Echoed if provided by the client in the corresponding request",
  "error": {
    "code": integer error code,
    "message": "Error message"
  }
}

• method=<string> The method name.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.
• error.code The error code.
• error.message The error message.

Error codes

There are no specific error codes for this method. General errors are listed under Error handling.

getOverlayCapabilities

getOverlayCapabilities returns the number of total overlay slots, the number of slots occupied per text overlay and the number of slots occupied per image overlay.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "getOverlayCapabilities"
}

• method="getOverlayCapabilities" Specifies that the getOverlayCapabilities operation is performed.
• context=<string> Optional. Client sets this value and server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
• apiVersion The API version that the response should use.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "method": "getOverlayCapabilities",
  "context": <string>,
  "apiVersion": "1.0",
  "data": {
    "numAvailableSlots": <integer>,
    "slotsPerImageOverlay": <integer>,
    "slotsPerTextOverlay": <integer>
  }
}

• method="getOverlayCapabilities" The method described in this section.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.
• apiVersion Current version is 1.0.
• data.numAvailableSlots=<integer> The number of slots available that can be used by overlays.
• data.slotsPerImageOverlay=<integer> The number of slots an image overlay occupies.
• data.slotsPerTextOverlay=<integer> The number of slots an text overlay occupies.

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "method": "The called method",
  "context": "Echoed if provided by the client in the corresponding request",
  "error": {
    "code": integer error code,
    "message": "Error message"
  }
}

• method=<string> The method name.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.
• error.code The error code.
• error.message The error message.

Error codes

There are no specific error codes for this method. General errors are listed under Error handling.

Error handling

General JSON error codes

The following table lists general error that can occur for any CGI method. Errors that are specific for a method are listed under the API description for that method.

Code	Description
100	The requested API version is not supported.
101	Internal error.
102	A mandatory input parameter was not found in the input.
103	Invalid parameter.
200	The provided input was invalid.
201	Unexpected error.
202	Generic error.
203	Invalid method.

Return value - Failure

If a request fails the response follows for the following syntax.

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "Major.Minor",
  "method": "The called method",
  "context": "Echoed if provided by the client in the corresponding request",
  "error": {
    "code": integer error code,
    "message": "Error message"
}

• apiVersion=<string> Current version is 1.0.
• method=<string> The method name.
• context=<string> Text-string echoed back if provided by the client in the corresponding request.
• error.code The error code.
• error.message The error message.

Overlay modifiers

Description

Overlay modifiers is to describe the Overlay modifiers functionality in Axis products.

Overlay modifiers are markup strings that when present in overlay text strings are expanded according to their corresponding function.

Modifiers can, among other things, be used to:

• insert text, such as date, time, system and sensor information, into the video stream that will be recorded together with the image.
• format file names, folders for uploaded images, notification messages and text in image overlays.
• retrieve functional groups and supported modifiers.

Function	Usage
getOverlayModifiers	Retrieve supported overlay modifiers.

Overview

Model

The API consists of the single CGI overlaymodifiers.cgi which allows querying for supported overlay modifiers.

Identification

• Property: Properties.OverlayModifiers.OverlayModifiers="yes"
• Firmware: 5.1 and later

Common examples

Present supported modifiers

This example will show you how to create a list of overlay modifiers for other users to choose from.

1. Retrieve a list of available groups and modifiers.

http://myserver/axis-cgi/overlaymodifiers.cgi

2. Parse JSON response.

Successful response example

{
  "apiVersion": "0.2",
  "context": 1,
  "method": "getOverlayModifiers",
  "data": {
    "groups": {
      "data": [
        {"mod": "%c"},
        {"mod": "%D"},
        {"mod": "%F"},
        {"mod": "%X"}
      ],
      ........
      "sysinfo": [
        {"mod": "#i"},
        {"mod": "#m"},
        {"mod": "#M"},
        {"mod": "#n"},
        {"mod": "#TC", "index": true},
        {"mod": "#TF", "index": true}
      ],
      ........
    }
  }
}

Error response example

{
  "apiVersion": "0.2",
  "context": "1",
  "method": "getOverlayModifiers",
  "error": {
    "code": 1000,
    "message": "Internal Error"
  }
}

3. Create a list and present it to the user.

API documentation

getOverlayModifiers

This method should be used when you want to retrieve overlay modifiers supported by your device.

Request

• Security level: Operator
• Method: GET

http://<servername>/axis-cgi/overlaymodifiers.cgi

Parameter	Description
context	Integer user data either echoed in the response or returned as 0 when left out (optional).

Return value - Success

Returns available groups along with an array of modifiers.

• HTTP Code: 200 OK
• Content-Type: application/json

Response body syntax

{
  "apiVersion": "0.2",
  "context": 1,
  "method": "getOverlayModifiers",
  "data": {
    "groups": {
      "data": [
        {"mod": "%c"},
        {"mod": "%D"},
        {"mod": "%F"},
        {"mod": "%X"}
      ],
      ........
      "sysinfo": [
        {"mod": "#i"},
        {"mod": "#m"},
        {"mod": "#M"},
        {"mod": "#n"},
        {"mod": "#TC", "index": true},
        {"mod": "#TF", "index": true}
      ],
      ........
    }
  }
}

See Schema for overlaymodifiers.cgi response for the JSON schema.

Return value - Failure

N/A, can only fail on a HTTP level.

Overlay modifiers properties

Parameter	Description
"apiVersion": {"type": "string"}	The API version that the data complies with.
"context": {"type": "integer"}	Set by the user in the request and echoed in the response. Automatically becomes 0 when not set in the request.
"method": {"type": "string"}	The requested method.
"data": {object}	A container for group objects.
"groups": [{objects}]	An array of objects detailing the modifiers belonging to the group.

"properties": {
  "mod": {"type": "string"},
  "index": {"type": "boolean"}
}

See Overlay modifier groups for a complete list of available groups.

Parameter	Description
"mod": {"type": "string"}	A modifier always starts with either a % or # character, followed by one or two characters and an index. Modifiers that require an index has the optional parameter index set to true, as detailed below. See Overlay modifiers for a complete list of available modifiers.
"index": {"type": "boolean"}	Optional property that exists in overlay modifiers that requires an additional index to be complete, for example modifiers #U, #TC and #TF are used to determine which fan or temperature sensor the modifier applies to. A modifier for fan 1 status would then be #U1 and for temperature sensor 2, in Celsius, #TC2.

Schema for overlaymodifiers.cgi response

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Axis Overlay Modifiers JSON Schema",
  "description": "Axis Overlay Modifiers schema for JSON requests and responses",
  "type": "object",
  "allOf": [{"$ref": "#/definitions/overlaymodifiers_response"}],

  "definitions": {

      "array_of_modifiers": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
          "mod": {"type": "string"},
          "index": {"type": "boolean"}
        },
        "required": ["mod"],
        "additionalProperties": false
      }
    },

    "overlaymodifiers_response": {
      "properties": {
        "apiVersion": {
          "type": "string"
        },
        "context":{
          "type": "integer"
        },
        "method": {
          "type": "string"
        },
        "data": {
          "type": "object",
          "properties": {
            "groups": {
              "type": "object",
              "properties": {
                "date": {"$ref": "#/definitions/array_of_modifiers"},
                "time": {"$ref": "#/definitions/array_of_modifiers"},
                "date": {"$ref": "#/definitions/array_of_modifiers"},
                "time": {"$ref": "#/definitions/array_of_modifiers"},
                "year": {"$ref": "#/definitions/array_of_modifiers"},
                "month": {"$ref": "#/definitions/array_of_modifiers"},
                "week": {"$ref": "#/definitions/array_of_modifiers"},
                "day": {"$ref": "#/definitions/array_of_modifiers"},
                "hour": {"$ref": "#/definitions/array_of_modifiers"},
                "minute": {"$ref": "#/definitions/array_of_modifiers"},
                "second": {"$ref": "#/definitions/array_of_modifiers"},
                "sysinfo": {"$ref": "#/definitions/array_of_modifiers"},
                "vidinfo": {"$ref": "#/definitions/array_of_modifiers"},
                "ptzinfo": {"$ref": "#/definitions/array_of_modifiers"},
                "eventinfo": {"$ref": "#/definitions/array_of_modifiers"},
                "sensor": {"$ref": "#/definitions/array_of_modifiers"},
                "mqtt": {"$ref": "#/definitions/array_of_modifiers"},
                "others": {"$ref": "#/definitions/array_of_modifiers"}
              }
            }
          },
          "required": ["groups"],
          "additionalProperties": false
        },
        "required": ["apiVersion", "data"],
        "additionalProperties": false
      }
    }
  }
}

Overlay modifier groups

Group	Description
date	Group Date - according to libc standard
time	Group Time - according to libc standard
year	Group Year - according to libc standard
month	Group Month - according to libc standard
week	Group Week - according to libc standard
day	Group Day - according to libc standard
hour	Group Hour - according to libc standard
minute	Group Minute - according to libc standard
second	Group Second - according to libc standard
sysinfo	Group Product and system information
vidinfo	Group Video information
ptzinfo	Group Pan/Tilt/Zoom information
sensor	Group Sensor and Optics
zwave	Group Z-Wave
mqtt	Group MQTT
others	Group Others

Overlay modifiers

Date modifiers

Modifiers	Description	Example
%c	Date and time.	Sun Dec 25 10:25:01 2011
%D	Date in format MM/DD/YY.	12/25/11
%F	Date in format YYYY-MM-DD.	2011–12–25
%x	Same as %D.	12/25/11

Time modifiers

Modifier	Description	Example
%p	AM or PM according to the given time or the corresponding strings for the current locale. Noon is treated as PM and midnight as AM.	AM
%r	Time in AM or PM notation.	10:25:01 AM
%R	Time in 24–hour notation without seconds.	10:25
%T	Time in 24–hour notation with seconds.	10:25:01
%X	Same as %T.	10:25:01
%z	Time zone as offset from UTC.	+0000
%Z	Time zone name or abbreviation.	GMT

Year modifiers

Modifier	Description	Example
%C	The century as a 2–digit number (year/100).	20
%G	The ISO 8601 week-numbering year as a 4–digit number.	2011
%g	The ISO 8601 week-numbering year as a 2–digit number without the century, range 00 to 99.	11
%Y	The Gregorian calendar year as a 4–digit number.	2011

Month modifiers

Modifier	Description	Example
%b	Abbreviated month name.	Dec
%B	Full month name.	December
%h	Same as %b.	Dec
%m	Month as a 2–digit number, range 01 to 12.	12

Week modifiers

Modifier	Description	Example
%U	The week number as a 2–digit number, range 00 to 53. Sunday is the first day of the week. Week 01 is the week starting with the first Sunday of the current year.	52
%V	The ISO 8601 week number as a 2–digit number, range from 01 to 53. Monday is the first day of the week. Week 01 is the first week that has at least four days in the current year.	51
%W	The ISO 8601 week number as a 2–digit number, range from 01 to 53. Monday is the first day of the week. Week 01 is the week starting with the first Monday of the current year.	51

Day modifiers

Modifier	Description	Example
%a	Abbreviated weekday name.	Sun
%A	Full weekday name.	Sunday
%d	Day of the month as a 2–digit number, range from 01 to 31.	25
%e	Same as %d but a leading zero is replaced by a blank space.	25
%j	Day of the year as a 3–digit number, ranging from 001 to 366.	359
%u	Day of the week as an 1–digit number, ranging from 1 to 7. Monday is 1.	7
%w	Day of the week as an 1–digit number, ranging from 0 to 6. Sunday is 0.	0

Hour modifiers

Modifier	Description	Example
%H	Hour in 24–hour format, ranging from 00 to 23.	09
%I	Hour in 12–hour format, ranging from 01 to 12.	09
%k	Same as %H but a leading zero is replaced by a blank space.	9
%l	Same as %I but a leading zero is replaced by a blank.	9

Minute modifiers

Modifier	Description	Example
%M	Minute as a 2–digit number, range 00 to 59.	25

Second modifiers

Modifier	Description	Example
%f	1/100 seconds as a 2–digit number.	67
%s	The number of seconds since EPOCH, that is, since 1970–01–01 00:00:00 UTC.	1319178723
%S	The current seconds as a 2–digit number, ranging from 00 to 59.	10

Product and system information modifiers

Modifier	Description	Example
#i	The IP address.	10.13.24.88
#m	The short MAC address (last 6 characters).	77:F8:26
#M	The full MAC address (all characters).	00:40:8C:77:F8:26
#n	The host name.	axis-00408c77f826
#U<index>	The fan status. <index> is which fan, for example #U1.	Stopped
#TC<index>	The temperature in Celsius. <index> is which temperature sensor, for example #TC1.	48.4
#TF<index>	The temperature in Fahrenheit. <index> is which temperature sensor, for example #TF1.	119.1

Video information modifiers

Modifier	Description	Example
#b	Bit rate in kbit/s (no decimals).	16333
#B	Bit rate in Mbit/s (two decimals).	16.33
#r	Frame rate with two decimals.	30.00
#R	Frame rate without decimals.	30
#v	Video source number.	1

Pan/tilt/zoom information modifiers

Modifier	Description	Example
#x	Pan coordinate (signed, with two decimals).	-77.61
#y	Tilt coordinate (signed, with two decimals).	-7.61
#z	Zoom coordinate (range 1 to 19999).	256
#Z	Zoom magnification (with one decimal).	12.0
#p	Preset position number. If not a preset position, blank space is used.	3
#P	Preset name. If not a preset position, blank space is used.	Door
#L	OSDI (On Screen Directional Indicator) zone name. A zone within specified pan and tilt coordinates. If not within an OSDI zone, blank space is used.	Construction

Sensor and optics modifiers

Modifier	Description	Example
#av	Current aperture value.	2.8
#al	Lowest aperture value.	2.8
#ah	Highest aperture value.	32
#gv	Current gain value (dB).	10
#gl	Lowest gain value (dB).	0
#gh	Highest gain value (dB).	60
#Gv	Current ISO gain value (ASA).	320
#Gl	Lowest ISO gain value (ASA).	100
#Gh	Highest ISO gain value (ASA).	102400
#hv	Current shutter value (seconds).	1/250.0
#hl	Lowest shutter value (seconds).	1/1.0
#hh	Highest shutter value (seconds).	1/4000.0
#lv	Current focal length value (mm).	50.0
#ln	Current lens name.	EF85mm f/1.2L II USM

Z-Wave modifiers

Modifier	Description	Example
#WB<index>	Battery status in percentage. <index> is the node ID (1–232), for example #WB1.	32
#WOS<index>	The output switch status (on/off). <index> is the node ID (1–232), for example #WOS1.	1
#WTC<index>	Temperature, in Celsius, of a multilevel sensor. <index> is the node ID (1–232), for example #WTC1.	48.4
#WTF<index>	Temperature, in Fahrenheit, of a multilevel sensor. <index> is the node ID (1–232), for example #WTF1.	119.1
#WIS<index>	The input switch status (on/off). <index> is the node ID (1–232), for example #WOS1.	1

MQTT modifiers

Modifier	Description	Example
#XMP<index>	Displays the full MQTT payload on the subscription of a topic tied to index.	{temperature_data: 23.2}
#XMD<index>	Displays specific data fields in an MQTT payload on the subscription of a topic tied to <index>. The payload is a text string and must be written in the JSON format.	23.2

Other modifiers

Modifier	Description	Example
#s	Sequence number of the video image as a 5–digit number.	00129
#D<index>	Dynamic text in an overlay. <index> is optional and specifies a dynamic text slot. See Dynamic text overlay for additional information.
%%	The % character.	%
##	The # character.	#

Privacy mask API

Privacy masking is a feature that makes it possible to mask out, i.e. cover areas in the picture that should not be visible to the viewers, such as the face of a person, logotypes and license plates. The masks will adapt their position and size when the cameras pan/tilt/zoom position changes to make sure that areas that have been masked remain that way.

Mask shape

The shape of a privacy mask is defined by a list of corner coordinates that either forms a rectangle or a polygon. Which form that is supported is described by a property parameter.

• If Properties.PrivacyMask.Polygon=yes is active, then a simple polygon shape is supported byProperties.PrivacyMask.MaxNbrOfCorners corners .
  The corners should be sorted in a clockwise rotation around the polygon, however, it’s up to the client to decide on the starting corner.
• The other option supports 4 corners in the shape of a rectangle, where the corners should be sorted in a clockwise rotation starting at the upper left corner.

Prerequisites

Identification

• API Discovery: id=privacy-mask version=3.x

• Property

  Properties.API.HTTP.Version=3

• Property

  Properties.PrivacyMask.PrivacyMask=yes

A number of additional properties are used to signal support for various privacy mask features:

• Property: Properties.PrivacyMask.MaxNbrOfPrivacyMasks=<number of supported privacy masks>
• Property: Properties.PrivacyMask.Polygon=<yes/no>
• Property: Properties.PrivacyMask.MaxNbrOfCorners=<int>
• Property: Properties.PrivacyMask.Query=<list of supported query types>
• Property: Properties.PrivacyMask.MainSwitch=<yes/no>
• Property: ImageSource.NbrOfSources=<number of image sources>

Dependencies

There currently exist two ways to create privacy masks. One is by using privacymask.cgi and the other by using param.cgi. Some functions, such as color and mosaic scale, can only be set using param.cgi, which means that some products will be using both.

• For cameras lacking support for privacymask.cgi, param.cgi is used on its own, as these cameras cannot adapt mask positions when the pan/tilt/zoom positions change, e.g. when connecting an external PTZ head on the serial port for a fix camera. Masks created on DPTZ are not affected by this.
• Cameras supporting the param.cgi use the "add", "update" and "remove" options described in Parameter management. Using the "add" option in the param.cgi will create new privacy masks denoted M0, M1 and M2, up to the maximum number of supported privacy masks.

Common examples

Add a privacy mask to the center of the image

Add a privacy mask named mask1 to the center of the image. The width and height of the mask are set in percent of the image size.

http://<servername>/axis-cgi/privacymask.cgi?action=add&name=mask1&imagesource=2&width=20.0&height=20.0

Add and position a privacy mask to the image

Add a privacy mask named mask1 centered around 20% of the image width and 20% of the image height of the picture. Width and height are set in percent of the image size.

http://<servername>/axis-cgi/privacymask.cgi?action=add&name=mask1&width=20.0&height=20.0&center=20.0,20.0

Add a privacy mask to the image using pixel coordinates

Add a privacy mask named mask1 using pixel coordinates to set the position of the mask.

http://<servername>/axis-cgi/privacymask.cgi?action=add&name=mask1&pxpolygon=500,500:800,500:700,700:400,700

Retrieve information about the size of a privacy mask

Get width and height for privacy mask p1.

http://<servername>/axis-cgi/privacymask.cgi?query=positionpxjson&name=Mask1

Add multiple privacy masks

Add two privacy masks named mask1 and mask2 using the param.cgi.

http://<servername>/axis-cgi/param.cgi?action=add&template=0_maskwindows&group=Image.I0.Overlay.MaskWindows
&Image.I0.Overlay.MaskWindows.M.Enabled=yes&Image.I0.Overlay.MaskWindows.M.Width=250 
&Image.I0.Overlay.MaskWindows.M.Height=300&Image.I0.Overlay.MaskWindows.M.Xpos=500 
&Image.I0.Overlay.MaskWindows.M.YPos=400&Image.I0.Overlay.MaskWindows.M.Name=mask1

http://<servername>/axis-cgi/param.cgi?action=add&template=0_maskwindows&group=Image.I0.Overlay.MaskWindows
&Image.I0.Overlay.MaskWindows.M.Enabled=yes&Image.I0.Overlay.MaskWindows.M.Width=200 
&Image.I0.Overlay.MaskWindows.M.Height=100&Image.I0.Overlay.MaskWindows.M.Xpos=200 
&Image.I0.Overlay.MaskWindows.M.YPos=100&Image.I0.Overlay.MaskWindows.M.Name=mask2

Rename a privacy mask

Rename the previously created mask2 to mask2_old using param.cgi.

http:<servername>/axis-cgi/param.cgi?action=update&Image.I0.Overlay.MaskWindows.M1.Enabled=yes&Image.I0.Overlay.MaskWindows.M1.Width=200&Image.I0.Overlay.MaskWindows.M1.Height=100&Image.I0.Overlay.MaskWindows.M1.Xpos=200&Image.I0.Overlay.MaskWindows.M1.YPos=100&Image.I0.Overlay.MaskWindows.M1.Name=mask2_old

Remove privacy masks

Remove the previously created mask1 and mask2_old using param.cgi.

http://<servername>/axis-cgi/param.cgi?action=remove&group=Image.I0.Overlay.MaskWindows.M0,Image.I0.Overlay.MaskWindows.M1

Disable all privacy masks

Disables all privacy masks. This is useful during an emergency when you want to make sure that nothing vital gets hidden behind a mask.

1. Disable all privacy masks.

http://<servername>/axis-cgi/privacymask.cgi?action=disable_all

2. Enable all privacy masks.

http://<servername>/axis-cgi/privacymask.cgi?action=enable_all

Please note that this method will disable all masks. If you wish to disable individual privacy masks you should use param.cgi.

Parameters

Using privacymask.cgi

Image.I#.Overlay.MaskWindows

Parameter	Default values	Valid values	Access control	Description
Color	black	black grey white red mosaic Hardware dependentchameleon Hardware dependent	admin: read, write	Set the color for the privacy masks of Image.I#.black = Black colored privacy mask. grey = Grey colored privacy mask. white = White colored privacy mask. red = Red colored privacy mask. mosaic = Pixelated (chessboard) privacy mask. Each pixel in a square have the same color, which is decided by the image behind the privacy mask. The square will adapt to the zoom level of a camera to keep the object behind the privacy mask obscured. chameleon = Changes color depending on the background. For example, if the mask is covering a red wall, the mask will become red.
MosaicScale Hardware dependent	3	3–16	admin: read, write	Set the mosaic effect scale for privacy masks of Image.I# when color is set to mosaicDefines the size of the squares in the mosaic, such as 8x8, 16x16, etc.

Image.I#.Overlay:MaskWindows.M#

Parameter	Default values	Valid values	Access control	Description
Enabled	no	yes, no	admin: read, write	Decides whether the privacy mask should be visible in the picture.yes = Privacy mask is visible. no = Privacy mask is not visible.
Name	<Mask#>	String	admin: read, write	The name of the privacy mask.
ZoomLowLimit	0	0 ... 19999	admin: read, write	Hides the privacy mask if the current zoom value is below the parameter value.

The index in Image.I# represents the video channel.

The index in MaskWindows.M# represents the index of the privacy mask.

Using param.cgi

Image.IO.Overlay.MaskWindows

Parameter	Default values	Valid values	Access control	Description
Color	black	black grey white red blurred Hardware dependent	admin: read, write	Set the color for the privacy masks of Image.I#.black = Black colored privacy mask. grey = Grey colored privacy mask. white = White colored privacy mask. red = Red colored privacy mask. blurred = Pixelated (chessboard) privacy mask. Each pixel in a square have the same color, which is decided by the image behind the privacy mask. The square will have a fixed size of 8x8 pixels.

Image.IO.Overlay.MaskWindows.M#

Parameter	Default values	Valid values	Access control	Description
Enabled	no	yes, no	admin: read, write	Decides whether the privacy mask should be visible in the picture.yes = Privacy mask is visible. no = Privacy mask is not visible.
XPos	0	Integer	admin: read, write	The Privacy masks upper left corner is positioned at this horizontal position (0 = at the top).
YPos	0	Integer	admin: read, write	The Privacy masks upper left corner is positioned at this vertical position (0 = at the top).
Width	0	Integer	admin: read, write	Width of mask in pixel.
Height	0	Integer	admin: read, write	Height of mask in pixel.
Name	No name	String	admin: read, write	The name of the Privacy mask.

The index in Image.IO represents the video channel.

The index in MaskWindows.M# represents the index of the privacy mask.

Privacy mask arguments

If the Axis product supports pan, tilt or zoom it is also possible to set privacy masks via the privacymask.cgi.

• Access control: admin
• Method: GET

Syntax:

http://<servername>/axis-cgi/privacymask.cgi?
<argument>=<value>[<argument>=<value>...]

With the following parameters and values.

Argument	Valid values	Description
action=<string>	add Requires name argument. Requires either width and height , pxpolygon or ptpolygon. update Requires name argument. Requires either width and height , pxpolygon or ptpolygon. remove Requires name argument. goto Requires name argument. enable_all disable_all	add = Add a new mask with unique name. update = Change position and/or size of existing mask. remove = Remove an existing mask. goto = Center camera on an existing mask. For modifying existing masks. enable_all = Enables all masks. The parameter Image.I#.Overlay.MaskWindows.M#.Enabled will be set to yes for all configured masks. Supported if root.Properties.PrivacyMask.MainSwitch=yes. disable_all = Disables all masks. The parameter Image.I#.Overlay.MaskWindows.M#.Enabled will be set to no for all configures masks. Supported if root.Properties.PrivacyMask.MainSwitch=yes.
query=<query>	listpxjson positionpxjson Requires name argument.	listpxjson = List all masks with pixel coordinates in the JSON format. The pixel coordinates are given in the max resolution of the camera and with rotation = 0 degrees. Two lists are returned, one containing only the external corners and one with both external and internal corners. External corners are provided by the user, while internal corners are added by the service. Supported if listed in root.Properties.PrivacyMask.Query. positionpxjson = List all masks with pixel coordinates in the JSON format. The pixel coordinates are given in the max resolution of the camera and with rotation = 0 degrees. Supported if listed in root.Properties.PrivacyMask.Query.
imagesource=<int>	0 ... n (n = number of image sources -1.)	Selects the Image source. If the Image source is omitted, the parameter defaults to 0.
name=<string>	<string>	Unique name to identify a mask. Maximum length is 128 characters.
width=<float>	0.0 ... 100.0	Width of mask, in percent of image width.
height=<float>	0.0 ... 100.0	Height of mask, in percent of image height.
center=<string>	0.0 ... 100.0,0.0 ...100.0	Center coordinates, in percentage of image width and image height, of the mask stored as float values in a string, width,height. Used together with width and height parameters. If left out the mask will be placed in the center of the picture.
pxpolygon=<int> Optional	<0,0:0,0:0,0>	Pixel coordinates of the corners of the privacy mask stored as integer values in a string of coordinated pairs, <x1>,<y1>:<x2>,<y2>:<x3>,<y3>. The pixel coordinates are given in the max resolution of the camera and with rotation = 0 degrees. The number of supported corners and the shape they represent is defined by root.Properties.PrivacyMask.MaxNbrOfCorners and root.Properties.PrivacyMask.Polygon.
zoomlowlimit=<int> Optional	0 ... 19999 If digital zoom is supported, zoomlowlimit can have values up to 19999.	The minimum VAPIX zoom position for the privacy mask to be rendered. At zoom values wider than this position the mask will not be rendered. Should be set to 0 if omitted. Notes: 1. Requires name argument. 2. Requires either width and height argument or pxpolygon argument.

Privacy mask responses

Successful response privacymask.cgi

Response after a successful request to privacymask.cgi.

• HTTP Code: 204 No content
• Content-Type: text/plain

Error response privacymas.cgi

Response after an incorrectly formatted or incomplete request to privacymask.cgi.

• HTTP Code: 200 OK
• Content-Type: text/plain

Error:
<Error message>

Successful response query=listpxjson

Response after a successful request to privacymask.cgi using query=listpxjson.

• HTTP Code: 200 OK
• Content-Type: application/json

{"listpx": [
    {"id": <int>,
      "name": "<Mask name1>",
      "enabled": <bool>,
      "zoomlowlimit": <int>,
      "zoom_visible": <bool>,
      "position": [
        {"x": <int>, "y": <int>},
        ...
      ]
      "all_position": [
        {"x": <int>, "y": <int>},
        ...
      ]
    },
    ...
  ]
}

Please note that pixel coordinates for a corner that is outside the current camera view will have values that are negative or larger than the image´s resolution.

zoom_visible is optional. If present, it will indicate whether the position polygon is visible due to the zoomlowlimit setting.

Position array can contain up to Properties.PrivacyMask.MaxNbrOfCorners x/y pairs. If the privacy mask is not visible in the current camera position, an empty position array will be returned.

all_position is optional. If present, it will contain the values found in position, as well as any helper corners added by the service.

Successful response query=positionpxjson

Response after a successful request to the privacymask.cgi using query=positionpxjson.

• HTTP Code: 200 OK
• Content-Type: application/json

{"position": [
    {"x": <int>, "y": <int>},
    ...
  ],
}

note

Pixel coordinates for a corner that is outside the current camera view will have values that are negative or larger than the image´s resolution.

Position array may contain up to Properties.PrivacyMask.MaxNbrOfCorners x/y pairs. If the privacy mask is not visible in the current camera position, an empty position array will be returned.

Text overlay API

Description

The text overlay is a text field that can be included in the top or bottom of the video image from an Axis product. The functionality can be used for showing static text, pan, tilt and zoom coordinates, preset positions, bit rate, etc. In addition to that it is also allowed to insert dynamic text, for example from an application. The dynamic text is contained in the RAM memory only and is removed on boot.

Prerequisites

Identification

• Property: Properties.API.HTTP.Version=3
• Firmware: 5.00 and later.

Common examples

Enable text overlay and add "My Overlay" as text overlay.

http://myserver/axis-cgi/param.cgi?action=update
&Image.I0.Text.TextEnabled=yes&Image.I0.Text.String=My%20Overlay

Enable text overlay and add date and time using modifiers.

http://myserver/axis-cgi/param.cgi?action=update
&Image.I0.Text.TextEnabled=yes&Image.I0.Text.String=%25F-%25H-%25M-%25S

Enable text overlay and dynamic text overlay.

http://myserver/axis-cgi/param.cgi?action=update
&Image.I0.Text.TextEnabled=yes&Image.I0.Text.String=%23D

Set the dynamic text overlay to "Test text" for cameras 1, 3 and 4.

http://myserver/axis-cgi/dynamicoverlay.cgi?
action=settext&camera=1,3,4&text=Test%20text

Get the dynamic text overlay from camera 2.

http://myserver/axis-cgi/dynamicoverlay.cgi?action=gettext
&camera=2

Parameters

Image.I#.Text

To add a text overlay for all video formats the parameters in this group should be used.

Image.I#.Text

Parameter	Default values	Valid values	Access control	Description
BGColor	black	white black transparent semitransparent	admin: read, write operator: read, write	Set the text background color.white = White text background color black = Black text background color transparent = Transparent text background color semitransparent = Semi transperent text background color
ClockEnabled	no	yes no	admin: read, write operator: read, write	Show/hide the time stamp.yes = Show the time stamp. no = Hide the time stamp.
Color	white	white black	admin: read, write operator: read, write	Set the text color.white = White text color. black = Black text color.
DateEnabled	no	yes no	admin: read, write operator: read, write	Show/hide the date.yes = Show the date. no = Hide the date.
Position	top	top bottom	admin: read, write operator: read, write	Position the text at the top or at the bottom in the image.top = Position the text at the top in the image. bottom = Position the text at the bottom in the image.
String		A string	admin: read, write operator: read, write	Set the overlay text. The string must be URL encoded.
TextEnabled	no	yes no	admin: read, write operator: read, write	Enable/disable text overlay.yes = Enable text overlay. no = Disable text overlay.

note

See https://www.axis.com/support/faq/Network%20Cameras/FAQ116391 for compatibility information.

Modifiers

Modifiers can be used to format file names, folders for uploaded images, notification messages, text in image overlays and similar. A modifier always starts with a % or # character, followed by another character.

The percent ("%") and hashtag ("#") must be percent-encoded. That means:

• % = %25
• # = %23

Use image-%F-%H-%M-%S.jpg so timestamp uploaded video snapshots with the date, hour, minute and second the snapshot was taken.

The following modifiers are available:

Date

Modifier	Description	Example
%c	Date and time.	Sun Dec 25 10:25:01 2011
%D	Date in format MM/DD/YY.	12/25/11
%F	Date in format YYYY-MM-DD.	2011–12–25
%x	Same as %D.	12/25/11

Time

Modifier	Description	Example
%p	AM or PM according to the given time or the corresponding strings for the current locale. Noon is treated as PM and midnight as AM.
%r	Time in a.m or p.m. notation.	10:25:01 AM
%R	Time in 24-hour notation without seconds.	10:25
%T	Time in 24-hour notation with seconds.	10:25:01
%X	Same as %T.
%z	Time zone as offset from UTC.	+0000
%Z	Time zone name or abbreviation.	GMT

Year

Modifier	Description	Example
%C	The century as a 2-digit number (year/100).	20
%G	The ISO 8601 week-numbering year as a 4-digit number.	2011
%g	The ISO 8601 week-numbering year as a 2-digit number without the century, range 00 to 99.	11
%Y	The Gregorian calendar year as a 4-digit number.	2011
%y	The Gregorian calendar year as a 2-digit number without the century, range 00 to 99.	11

Month

Modifier	Description	Example
%b	Abbreviated month name.	Dec
%B	Full month name.	December
%h	Same as %b.
%m	Month as a 2-digit number, range 01 to 12.	12

Week

Modifier	Description	Example
%U	The week number as a 2-digit number, range 00 to 53. Sunday is the first day of the week. Week 01 is the week starting with the first Sunday of the current year.	52
%V	The ISO 8601 week number as a 2-digit number, range 01 to 53. Monday is the first day of the week. Week 01 is the first week that has at least four days in the current year.	51
%W	The week number as a 2-digit number, range 00 to 53. Monday is the first day of the week. Week 01 is the week starting with the first Monday of the current year.	51

Day

Modifier	Description	Example
%a	Abbreviated weekday name.	Sun
%A	Full weekday name.	Sunday
%d	Day of the month as a 2-digit number, range 01 to 31.	25
%e	Same as %d but a leading zero is replaced by a blank space.	25
%j	Day of the year as a 3-digit number, range 001 to 366.	359
%u	Day of the week as an 1-digit number, range 1 to 7. Monday is 1.	7
%w	Day of the week as an 1-digit number, range 0 to 6. Sunday is 0.	0

Hour

Modifier	Description	Example
%H	Hour in 24-hour fomat, range 00 to 23.	10
%I	Hour in 12-hour format, range 01 to 12.	10
%k	Same as %H but a leading zero is replaced by a blank space.
%l	Same as %I but a leading zero is replaced by a blank space.

Minute

Modifier	Description	Example
%M	Minute as a 2-digit number, range 00 to 59.	25

Second

Modifier	Description	Example
%f	1/100 seconds as a 2-digit number.	67
%s	The number of seconds since EPOCH, that is, since 1970–01–01 00:00:00 UTC.	1319178723
%S	The current second as a 2-digit number, range 00 to 59.	10

Product and system information

Modifier	Description	Example
#i	The IP address.	10.13.24.88
#m	The short MAC address (last 6 characters).	77:F8:26
#M	The full MAC address (all characters).	00:40:8C:77:F8:26
#n	The host name.	axis-00408c77f826
#U<index>	The fan status. <index> = A specified fan. For example 1.	Stopped
#TC<index>	The temperature of the camera sensor in Celsius. <index> = A specified camera sensor. For example 1.	48,4
#TF<index>	The temperature of the camera sensor in Fahrenheit. index> = A specified camera sensor. For example 1.	119,1

Video information Bit rate and frame rate modifiers are available in products with ARTPEC® chips.

Modifier	Description	Example
#b	Bit rate in kbit/s (no decimals).	16333
#B	Bit rate in Mbit/s (two decimals).	16.33
#r	Frame rate with two decimals.	30.00
#R	Frame rate without decimals.	30
#v	Video source number.	1

Pan/Tilt/Zoom information

Modifier	Description	Example
#x	Pan coordinate (signed, with two decimals).	—77.61
#y	Tilt coordinate (signed, with two decimals).	—7.61
#z	Zoom coordinate (range 1 to 19999).	256
#Z	Zoom magnification (with one decimal).	12.0
#p	Preset position number. If not at a preset position, blank space is used.	3
#P	Preset name. If not at a preset position, blank space is used.	Door
#L	OSDI (On Screen Directional Indicator) zone name. A zone within specified pan and tilt coordinates. If not within an OSDI zone, blank space is used.	Construction

Others

Modifier	Description	Example
#s	Sequence number of the video image as a 5-digit number.
#D	Dynamic text overlay.
%%	The % character.
##	The # character.

Dynamic text overlay

Dynamic text overlay can be inserted in the text overlay. Since dynamic text is saved in the RAM memory only is removed on boot.

It is possible to use modifiers starting with % in this dynamic text. Modifiers starting with # can however not be used.

To use this functionality set Image.I#.Text.TextEnabled to yes and set Image.I#.Text.String to contain the modifier #D.

note

The ‘#’ in I# should be replaced by an integer starting from zero. The ‘#’ in #D is a modifier and should not be replaced.

• Access control: operator
• Method: GET

Syntax:

http://<servername>/axis-cgi/dynamicoverlay.cgi?<argument>=<value>
[&<argument>=<value>...]

With the following arguments and values:

Argument	Valid values	Description
action=<string>	settext gettext	gettext = Get the dynamic text overlay. settext = Set the dynamic text overlay.
text=<string>	A string	The overlay text to apply, only applicable with action=settext.
text_index=<integer>	1...16	Select a dynamic text slot. A text index for a slot maps text to the modifiers #D1...#D16 . For example, text_index=3&text=Hello means that Hello will be mapped to #D3.
camera=<string>[,string,...]	1 (default) ... Product/release-dependent. Check the product’s release notes.	Selects the video channel. If omitted the default value camera=1 is used. This argument is only valid for Axis products with more than one video channel. That is cameras with multiple view areas and video encoders with multiple video channels.

Overlay image API

Description

The Overlay image API makes it possible for applications to upload and manage images used for image overlays and configure the default image used in stream profiles.

Model

The API consists of the following CGI:s:

Function	Description
axis-cgi/uploadoverlayimage.cgi	Used for uploading images to the camera. The request uses multipart/form-data with one part being in the JSON format and one part containing the image data.
axis-cgi/manageoverlayimages.cgi	Used for managing uploaded images. Requests and responses are in the JSON format.

• The uploadoverlayimage.cgi uses the following methods:

Method	Description
uploadOverlayImage	Upload an image to the camera.
getSupportedVersions	Get a list of supported API versions.

• The manageoverlayimages.cgi uses the following methods:

Method	Description
supportedFormats	Get a list of supported image formats.
validateImageHeader	Check if an image is supported based on provided image header data. It also checks that there is enough space available on the camera.
listImages	List all images present on the camera.
deleteImage	Delete an image.
getDefaultImage	Get the currently configured default image.
setDefaultImage	Set the default image.
getSupportedVersions	Get a list of supported API versions.

Identification

• API Discovery: id=overlayimage

Obsoletes

This API replaces the older Image overlay API (Old version).

Common examples

Upload a new image

Use this example to upload an image to use for an image overlay.

Upload image

1. Upload an image to the camera.

HTTP POST

POST /axis-cgi/uploadoverlayimage.cgi HTTP/1.0
Content-Type: multipart/form-data; boundary=---------------------------735323031399963166993862150
Content-Length: [...]
-----------------------------735323031399963166993862150
Content-Disposition: form-data; name="json"
Content-Type: application/json

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "params": {
    "scaleToResolution": true,
    "alpha": "ffffff"
  }
}
-----------------------------735323031399963166993862150
Content-Disposition: form-data; name="image"; filename="image.bmp"
Content-Type: image/bmp
[Image data]
-----------------------------735323031399963166993862150

CURL

curl --request POST 'http://<ip-address>/axis-cgi/uploadoverlayimage.cgi'
--digest -s -u '<username>:<password>'
--form 'json=@"request.json"'
--form 'image=@"image.bmp"'
request.json

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "params": {
    "scaleToResolution": true,
    "alpha": "ffffff"
  }
}

2. Parse the JSON response.

a) Successful response. The response returns the path of the image.

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "data": {
    "path": /etc/overlays/image.ovl
  }
}

b) Error response.

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "error": {
    "code": "1003",
    "message": "Invalid parameter"
  }
}

API references

uploadOverlayImage

List available images

Use this example to list all available overlay images.

List images

1. List all available images.

{
  "apiVersion": "1.0",
  "method": "listImages",
}

2. Parse the JSON response.

a) Successful response example. The response list all available images. For each image a path identifying the image and a flag indicating the scaleWithResolution status is provided.

{
  "apiVersion": "1.0",
  "method": "listImages",
  "data": {
    "files": [
      {"path": "/etc/overlays/image1.ov1", "scaleWithResolution": true},
      {"path": "/etc/overlays/image2.ov1", "scaleWithResolution": false}
    ]
  }
}

b) Error response example.

{
  "apiVersion": "1.0",
  "method": "listImages",
  "error": {
    "code": "1003",
    "message": "Invalid parameter"
  }
}

API references

listImages

Delete an image

Use this example to delete an overlay image.

Delete image

1. Delete an image.

{
  "apiVersion": "1.0",
  "method": "deleteImage",
  "params": {
    "path": "/etc/overlays/image.ovl"
  }
}

2. Parse the JSON response.

a) Successful response example. The response will give information if the image was successfully deleted or not.

{
  "apiVersion": "1.0",
  "method": "deleteImage",
}

b) Error response example.

{
  "apiVersion": "1.0",
  "method": "deleteImage",
  "error": {
    "code": "1003",
    "message": "Invalid parameter"
  }
}

API references

deleteImage

Set the default image

Use this example to set a default overlay image.

1. Set the default image.

{
  "apiVersion": "1.0",
  "method": "setDefaultImage",
  "params": {
    "path": "/etc/overlays/image.ovl"
  }
}

2. Parse the JSON response.

a) Successful response example. The response will give information if the default image was correctly set or not.

{
  "apiVersion": "1.0",
  "method": "setDefaultImage",
}

b) Error response example.

{
  "apiVersion": "1.0",
  "method": "setDefaultImage",
  "error": {
    "code": "1003",
    "message": "Invalid parameter"
  }
}

API references

setDefaultImage

API specification

uploadOverlayImage

uploadOverlayImage is used to upload a new overlay image by using a multipart/form-data.

The first part should contain a JSON request and be set up with the following parameters:

• Content-disposition

  form-data; name="json"

• Content-Type: application/json

The second part should contain the image data and should be set up with the following parameters:

• Content-disposition

  form-data; name="image"; filename=<name of file>

• Content-type

  <image mime-type>

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "method": "uploadOverlayImage",
  "context": <string>,
  "params": {
    "scaleToResolution": <boolean>,
    "alpha": <string>
  }
}

Parameter	Description
apiVersion	The current version of the API.
method="uploadOverlayImage"	Specifies that the uploadOverlayImage operation is performed.
context=<string>	Optional. The string echoed back in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
scaleToResolution	Required. Specifies if the image should be configured as "scale-to-resolution" or not. Scale-to-resolution means that the size of an overlay that uses this image will be scaled based on the stream resolution.
alpha	Optional. Specifies a color to use as transparency. This can be used to support transparency for BMP images that normally doesn’t support it. For image formats that support transparency this parameter is ignored.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "context": <string>,
  "data": {
    "path": <string>
  }
}

Parameter	Description
apiVersion	The current version of the API.
method="uploadOverlayImage"	The method described in this section.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
data.path	Path that should be used when referring to this image.

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Parameter	Description
apiVersion=<major>.<minor>	The API version that is used.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
method=<string>	The method described in this section.
error.code	Contains an error code. This method can be a method specific or a general error code.
error.message	Contains a detailed message about the occurred failure.

Error codes

See Error codes for a full list of potential error codes.

supportedFormats

supportedFormats is used to get a list of image formats supported by the camera. Possible values are:

• bmp
• jpeg
• png
• svg

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "method": "supportedFormats",
  "context": <string>
}

Parameter	Description
apiVersion	The current version of the API.
method="supportedFormats"	Specifies that the supportedFormats operation is performed.
context=<string>	Optional. The string echoed back in the response. If set, it will be present in the response regardless of whether the response is successful or an error.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "1.0",
  "method": "supportedFormats",
  "context": <string>,
  "data": {
    "formats": [<string>, <string>]
  }
}

Parameter	Description
apiVersion	The current of the API.
method="supportedFormats"	The method described in this section.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
data.formats	List of supported image formats.

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Parameter	Description
apiVersion=<major>.<minor>	The API version that is used.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
method=<string>	The method described in this section.
error.code	Contains an error code. This method can be a method specific or a general error code.
error.message	Contains a detailed message about the occurred failure.

Error codes

See Error codes for a full list of potential error codes.

validateImageHeader

validateImageHeader will check if the image described by the parameters are supported, is of an acceptable file-size and that there are enough memory on the device. In cases where there are an invalid parameter, an error response is sent and the status code is set to reflect what the problem might be.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "method": "validateImageHeader",
  "context": <string>,
  "params": {
    "type": <string>,
    "width": <int>,
    "height": <int>
  }
}

Parameter	Description
apiVersion	The current version of the API.
method="validateImageHeader"	Specifies that the validateImageHeader operation is performed.
context=<string>	Optional. The string echoed back in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
type=<string>	Required. The image type. Should be one of the values listed in the documentation for supportedFormats.
width=<integer>	Required. The width of the image.
height=<integer>	Required. The height of the image.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "1.0",
  "method": "validateImageHeader",
  "context": <string>,
  "data": {
    "supportsAlpha": <boolean>,
    "supportsScaling": <boolean>
  }
}

Parameter	Description
apiVersion	The current version of the API.
method="validateImageHeader"	The method described in this section.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
data.supportsAlpha	Indicates if an alpha value may be specified for this image.
data.supportsScaling	Indicates if scale-to-resolution is supported for this image.

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Parameter	Description
apiVersion=<major>.<minor>	The API version that is used.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
method=<string>	The method described in this section.
error.code	Contains an error code. This method can be a method specific or a general error code.
error.message	Contains a detailed message about the occurred failure.

Error codes

See Error codes for a full list of potential error codes.

listImages

listImages is used to get a list of available overlay images.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "method": "listImages",
  "context": <string>
}

Parameter	Description
apiVersion	The current version of the API.
method="listImages"	Specifies that the listImages operation is performed.
context=<string>	Optional. The string echoed back in the response . If set, it will be present in the response whether the response was successful or an error.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "1.0",
  "method": "listImages",
  "context": <string>,
  "data": {
    "files": [
      {"path": <string>, "scaleWithResolution": <boolean>},
      {"path": <string>, "scaleWithResolution": <boolean>}
    ]
  }
}

Parameter	Descriptions
apiVersion	The current version of the API.
method="listImages"	The method described in this section.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
data.files	The list of available images.
data.files.path	The path identifying the image.
data.files.scaleWithResolution	A flag indicating if the image is scaled with the stream resolution.

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "listImages",
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Parameter	Description
apiVersion=<major>.<minor>	The API version that is used.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
method=<string>	The method described in this section.
error.code	Contains an error code. This method can be a method specific or a general error code.
error.message	Contains a detailed message about the occurred failure.

Error codes

See Error codes for a full list of potential error codes.

deleteImage

deleteImage is used to delete an overlay image.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "method": "deleteImage",
  "context": <string>,
  "params": {
    "path": <string>
  }
}

Parameter	Description
apiVersion	The current version of the API.
method="deleteImage"	Specifies that the deleteImage operation is performed.
context=<string>	Optional. The string echoed back in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
path=<string>	Required. The path identifying the image.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "1.0",
  "method": "deleteImage",
  "context": <string>
}

Parameter	Description
apiVersion	The current version of the API.
method="deleteImage"	The method described in this section.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.

Return value-Failure

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Parameter	Description
apiVersion=<major>.<minor>	The API version that is used.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
method=<string>	The method described in this section.
error.code	Contains an error code. This method can be a method specific or a general error code.
error.message	Contains a detailed message about the occurred failure.

Error codes

See Error codes for a full list of potential error codes.

getDefaultImage

getDefaultImage retrieves the currently configured default overlay image.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "method": "getDefaultImage",
  "context": <string>
}

Parameter	Description
apiVersion	The current version of the API.
method="getDefaultImage"	Specifies that the getDefaultImage operation is performed.
context=<string>	Optional. The string echoed back in the response. If set, it will be present regardless of whether the response is successful or an error.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "1.0",
  "method": "getDefaultImage",
  "context": <string>,
  "data": {
    "path": <string>
  }
}

Parameter	Description
apiVersion	The current version of the API.
method="getDefaultImage"	The method described in this section.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
data.path=<string>	Path that should be used when referring to this image.

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Parameter	Description
apiVersion=<major>.<minor>	The API version that is used.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
method=<string>	The method described in this section.
error.code	Contains an error code. This method can be a method specific or a general error code.
error.message	Contains a detailed message about the occurred failure.

Error codes

See Error codes for a full list of potential error codes.

setDefaultImage

setDefaultImage is used to set the default overlay image.

Request

• Security level: Operator
• Method: POST

{
  "apiVersion": <string>,
  "method": "setDefaultImage",
  "context": <string>
  "params": {
    "path": <string>
  }
}

Parameter	Description
apiVersion	The current version of the API.
method="setDefaultImage"	Specifies that the setDefaultImage operation is performed.
context=<string>	Optional. The string echoed back in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
path=<string>	Required. The path identifying the image to set.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "1.0",
  "method": "setDefaultImage",
  "context": <string>
}

Parameter	Description
apiVersion	The current version of the API.
method="setDefaultImage"	The method described in this section.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Parameter	Description
apiVersion=<major>.<minor>	The API version that is used.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
method=<string>	The method described in this section.
error.code	Contains an error code. This method can be a method specific or a general error code.
error.message	Contains a detailed message about the occurred failure.

Error codes

See Error codes for a full list of potential error codes.

getSupportedVersions

getSupportedVersions is used to retrieve the list of supported API versions.

Request

• Security level: Operator
• Method: POST

http://<servername>/<functionality>.cgi

{
  "context": <string>,
  "method": "getSupportedVersions"
}

Parameter	Description
context=<string>	Optional. The string echoed back in the response. If set, it will be present in the response regardless of whether the response is successful or an error.
method="getSupportedVersions	Specifies that the getSupportedVersions operation is performed.

Return value - Success

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersion": ["<Major1>.<Minor1>", "<Major2>.<Minor2>"]
  }
}

Parameter	Description
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
method="getSupportedVersions"	The method described in this section.
data.apiVersion[]=<list of versions>	List of supported versions. All major versions are listed with their highest supported minor version.
<list of versions>	List of <Major>.<Minor> versions e.g. ["1.4", "2.5"].

Return value - Failure

• HTTP Code: 200 OK
• Content-Type: application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Parameter	Description
apiVersion=<major>.<minor>	The API version that is used.
context=<string>	The string echoed back if it is provided by the client in the corresponding request.
method=<string>	The method described in this section.
error.code	Contains an error code. This method can be a method specific or a general error code.
error.message	Contains a detailed message about the occurred failure.

Error codes

See Error codes for a full list of potential error codes.

Error codes

Error code	Description
1000	Internal error.
1001	The requested API version is not supported.
1002	Invalid method.
1003	Invalid parameter.
1004	The provided input was invalid.
1005	Image size is too big.
1006	Unsupported image format.
1007	Not enough space left on the device.
1008	Alpha is not supported.
1009	Scale-to-resolution is not supported.
1010	Image already exists.
1011	Image is being used by a dynamic overlay.
1012	Image is being used by a legacy overlay.
1013	Image is being used as default image.
1014	Image is being used by an overlay.

Image overlay API (Old version)

note

This API will no longer receive updates. For a newer version on how to upload and manage images used for image overlays, see Overlay image API.

Description

An overlay image is a static image superimposed over the video image. An overlay can for example be used to provide extra information, for example a logotype.

The uploaded image must be in one of the following formats:

• Windows 24-bit BMP (full color).
• Windows 4-bit BMP (16 colors).

The size of the overlay image in pixels (width by height) must be exactly divisible by 4.

The maximum overlay image size supported is the same as the maximum image resolution.

Prerequisites

Identification

• Property: Properties.API.HTTP.Version=3
• Firmware: 5.00 and later.

Common examples

Enable image overlay and place the image 10 pixels to the right and 900 pixels down from the top left corner.

http://myserver/axis-cgi/param.cgi?action=update&Image.I0.Overlay.Enabled=yes
&Image.I0.Overlay.Xpos=10&Image.I0.Overlay.Ypos=900

Parameters

Image.I#.Overlay

To add an image overlay for all video formats the parameters in this group should be used.

note

The video stream needs to be restarted for parameter values to take affect.

Image.I#.Overlay

Parameter	Default values	Valid values	Access control	Description
Enabled	no	yes no	admin: read, write operator: read, write	Enable/disable overlay image.The overlay image is stored in a file given by the parameter Image.OverlayPath.yes = Enable overlay image. no = Disable overlay image.
XPos	0	An unsigned integer.	admin: read, write operator: read, write	The overlays upper left corner is positioned at this horizontal position (0 = to the left).
YPos	0	An unsigned integer.	admin: read, write operator: read, write	The overlays upper left corner is positioned at this horizontal position (0 = at the top).

Image

This group contains a parameter to specify the location of the image file used in image overlay.

Image

Parameter	Default values	Valid values	Access control	Description
OverlayPath		<string>	admin: read, write operator: read, write	Specify the location of the image used in image overlay.

Upload image

Images uploaded to the image overlay folder are processed by the CGI call_overlay_upload.cgi.

For action=upload the POST method must be used; the file content is provided in the HTTP body. The image file should be uploaded using Multipart/Form-Data as defined in RFC 1867.

Body:

POST /axis-cgi/call_overlay_upload.cgi?action=upload HTTP/1.0
Content-Type: multipart/form-data; boundary=<boundary>
Content-Length: <content length>

--<boundary>
Content-Disposition: form-data; name="<name>";
filename="<file name>"
Content-Type: text/html

<file content>

--<boundary>