The possibility to create overlays via the parameter CGI will be partially deprecated in AXIS OS 11.5 and is planned to be removed with the next LTS. If you are using overlay modifications through parameter CGI, we recommend you start using the dedicated overlay API, dynamicoverlay CGI instead.

When overlays were introduced in Axis products the only way of creating them was through the parameter CGI. Users could create one text overlay and one image overlay, with some flexibility regarding properties. parameter CGI is a general API, which is practical as it exposes many different parts of the platform but limiting for developing depth within a specific feature. 

Today overlays have their own API, dynamicoverlay CGI, with direct access to the overlay system. dynamicoverlay CGI has been the recommended API for overlays for some time and has full coverage of the features that were exposed via parameter CGI.

From AXIS OS 11.5 when a user call param.cgi overlays, it will be converted/mapped to the first overlay of dynamic overlay API.

Benefits of this change

  • Having multiple API’s competing for mutual hardware resources is a common cause for misconception. By making this change we are unifying the ways overlays are handled.
  • The dynamicoverlay CGI is a modern API with more features. param.cgi can only control the one and the first overlay from the dynamic API whereas dynamic overlay API can control multiple overlays.

Considerations for developers and partners

  • The parameter CGI’s overlay parameters will, for now, work almost as before. The difference is that overlays created through this API will be part of the same system as overlays created through dynamicoverlay CGI and the camera GUI. This unification of ownership will cause less ambiguity when it comes to the mutual resources and will also result in a unified look and feel for all overlays, regardless which API was used to create them.
  • There will no longer be a clear distinction between overlays created via parameter CGI and overlays created through the camera GUI/dynamicoverlay CGI. This means that an overlay created via parameter CGI can be modified or removed by dynamicoverlay CGI, and vice versa. Even if the internal workings have been unified, both APIs still have a list on their own about their idea of the current overlay state.
  • We discourage using the parameter CGI and dynamicoverlay CGI at the same time as it may cause mismatches between the believed overlay state and the actual overlay state for each API.

Examples of how to create an overlay using dynamicoverlay CGI and parameter CGI

The major difference between the APIs is that dynamicoverlay CGI is a HTTP POST API, as opposed to parameter CGI which is a HTTP GET API. POST refers to the client used to send the message, such as curl or postman.

Create a Text Overlay

  • parameter CGI:


  • dyanmicoverlay CGI:


POST {"apiVersion": "1.0", "method": "addText", "params": {“camera”: 1, "text": "TEST”}}

The calls here are similar, the main difference being the way we communicate with the API, and that channel (I0, I1 etc.) has been replaced by camera, which starts at 1 instead.

Update a Text Overlay with position at bottom, with YY-MM-DD date and text

  • parameter CGI:


  • dyanmicoverlay CGI:


POST {"apiVersion": "1.0", "method": "setText", "params": {“identity”: 1, “position”:”bottom”, "text": "%F TEST”}}

Since there is only a single overlay slot for each image channel in parameter CGI, updating is done by overwriting existing values. When using dynamicoverlay CGI, we must explicitly state which overlay we use to update, since we can have several for each image channel. The identity of an overlay is returned upon creation. Furthermore, we see a difference in that there is no explicit setting for enabling the date. Instead, we use the modifier string directly in the text field. Modifiers are already usable via parameter CGIs text field, so nothing is new here.

Create a Text Overlay with large font size, black text color, white background, and the clock

  • parameter CGI:


  • dynamicoverlay CGI:


POST {"apiVersion": "1.0", "method": "addText", "params": {“camera”: 1, “fontSize”: 32, “textBGColor”: ”white”, “textColor”: “black”, "text": "%X”}}

As we saw in the last example, we once again use the modifier in the text field directly, instead of explicitly enabling the clock. Another difference is the fontSize-field, which now is expressed as an integer instead of a string. The mapping is as follows: small = 16, medium = 24, large = 32

Create an Image Overlay at custom position

  • parameter CGI:


  • dyanmicoverlay CGI:


POST {"apiVersion": "1.0", "method": "addImage", "params": {“camera”: 1, “overlayPath”: “/etc/overlays/axis(128x44).ovl”, “position”, “0,0”}}

Adding an image is like adding a text for both APIs. One difference is that position is no longer expressed as an absolute value based on screen resolution, but as a relative value between -1.0 and 1.0, or as a string (top, bottomLeft etc.).

Updating the image overlay is done in the same way as updating the text overlay, but for images we call setImage instead.

More information