# Using the REST API for static overlays
<a name="using-the-rest-api-for-static-overlays"></a>

**Topics**
+ [

# Static graphic overlay commands
](static-graphic-overlay-commands.md)
+ [

# Create or modify a non-running event with static graphic overlay
](create-or-modify-a-non-running-event-with-static-graphic-overlay.md)
+ [

# Modify static overlay on a running event
](modify-static-overlay-on-a-running-event.md)

# Static graphic overlay commands
<a name="static-graphic-overlay-commands"></a>


| Nickname | Action | Signature | Description | 
| --- | --- | --- | --- | 
| Create Event | POST | <Live IP address>/live\$1events | Create an event that includes static overlay information. | 
| Modify Event | PUT | <Live IP address>/live\$1events/live\$1event/<event ID> | Modify an event (that is not running) and add, modify or delete static overlay information. | 
| Modify Static Overlay, Running Event | POST | /live\$1event/<event ID>/image\$1inserter | All outputs: add, modify or delete static information in a running event. | 
| Modify Static Overlay, Running Event | POST |  `<Live IP Address>/live_events/<event ID>/ image_inserter/output/<output id>` Where `<output id>` is the unique ID automatically assigned to this output when the event is created.  | Specific output: add, modify or delete static information in a running event. | 
| Modify Static Overlay, Running Event | POST |  `<Live IP Address>/live_events/<event ID>/ image_inserter/output/by_stream/<stream id>` Where `<stream id>` is the unique ID automatically assigned to this stream when the event is created. The ID can change while the event is running (for example, if another stream is deleted), so you may need to obtain the current ID before sending this command.  | All outputs associated with a specific stream: add, modify or delete static information in a running event. | 
| Modify Static Overlay, Running Event | POST |  `<Live IP Address>/live_events/<event ID>/ image_inserter/input/<input id>` Where `<input id>` is the unique ID automatically assigned to this input when the event is created or when the input is added to the event.  | Specific input, all outputs associated with it: add, modify or delete static information in a running event. | 
| Modify Static Overlay, Running Event | POST |  `<Live IP Address>/live_events/<event ID>/ image_inserter/input/by_label/<input label>` Where `<input label>` is the input label you assigned when you created this event or created this input. Input labels are always optional.  | Specific input, all outputs associated with it: add, modify or delete static information in a running event. | 

# Create or modify a non-running event with static graphic overlay
<a name="create-or-modify-a-non-running-event-with-static-graphic-overlay"></a>

Create or modify an Elemental Live event and include one or more static graphic overlays. This description assumes that you are familiar with the XML body for a live\$1event aside from the data for the graphic overlay.

## HTTP request and response
<a name="http-request-and-response-non-running"></a>

**HTTP URL** 

```
POST http://<Live IP Address>/live_events
```

or: 

```
PUT http://<Live IP Address>/live_events/<event ID> 
```

**Body of request – one input** 

To insert the static overlay in one input element: 

XML content consisting of one live\$1event element that contains: 
+ All the usual elements and tags. 
+ One input element that contains: 
  + All the usual elements and tags. 
  + One image\$1inserter element that contains: 
    + One enable\$1rest tag. 
    + One insertable\$1images element that contains: 
      + 1 to 8 insertable\$1image elements that contain the tags listed in the following table.

For a representation of the XML structure, see [XML structure](xml-structure-static.md). 

**Body of request – all outputs **

To insert the static overlay in all outputs: 

XML content consisting of one live\$1event element that contains:
+ All the usual elements and tags. 
+ One image\$1inserter element that contains: 
  + One enable\$1rest tag. 
  + One insertable\$1images element that contains: 
    + 1 to 8 insertable\$1image elements that contain the tags listed in the table on the following page. 

For a representation of the XML structure, see [XML structure](xml-structure-static.md). 

**Body of request – outputs for one stream assembly **

To insert the static overlay in the outputs associated with a given stream. XML content consisting of one live\$1event element that contains: 
+ All the usual elements and tags. 
+ One stream\$1assembly element that contains: 
  + All the usual elements and tags. 
  + One image\$1inserter element that contains: 
    + One enable\$1rest tag. 
    + One insertable\$1images element that contains: 
      + 1 to 8 insertable\$1image elements that contain the tags listed in the following table. 

For a representation of the XML structure, see [XML structure](xml-structure-static.md). 

**Child elements of <insertable\$1image> and <image>**


| Element | Type | Required | Description for creating | 
| --- | --- | --- | --- | 
| activate | Boolean | Required |  Required when adding or modifying an overlay in a running event (not when creating an event or modifying a non-running event). This tag has no effect when creating or modifying a non-running event. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/create-or-modify-a-non-running-event-with-static-graphic-overlay.html) **Note: **<activate> is distinct from <active>, which is used with motion image inserter.  | 
| duration | Integer | Optional Default: until end of event |  The time in milliseconds for the overlay to remain on the video. When creating an event, if this field is left blank, the overlay will remain on the video as follows: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/elemental-live/latest/ug/create-or-modify-a-non-running-event-with-static-graphic-overlay.html) The total running time of the overlay is fade\$1in \$1 duration \$1 fade\$1out.  | 
| fade\$1in | Integer | Optional | The duration, in milliseconds, for the overlay fade-in. This time is inserted before the start time of the overlay. | 
| fade\$1out | Integer | Optional |  This field is valid only if the Duration field is completed. The duration, in milliseconds, for the overlay fade-out. This time is added to the overlay duration.  | 
| height | Integer |  Optional Default: native height of overlay  |  The height of the overlay when inserted in the video, in pixels. When creating an event, leave blank to use the native height of the overlay. The original overlay will be scaled up or down, to the specified height.  | 
| width | Integer |  Optional Default: native width of overlay  |  The width of the overlay when inserted in the video, in pixels. When creating an event, leave blank to use the native height of the overlay. The original overlay will be scaled up or down, to the specified width.  | 
| image\$1inserter\$1input | Location | Required |  Overlay PNG or BMP file to insert. For file requirement details, information about where to store this file, and how to specify its location, see [Step A: Prepare the overlay asset](step-a-prepare-the-overlay-asset.md).  | 
| image\$1x | Integer | Required |  Placement of the left edge of the overlay relative to the horizontal axis for the video frame, in pixels. 0 is the left edge of the frame. When creating an event, cannot be omitted. Take note of the width of the overlay and make sure that the position of the left edge of the overlay does not cause the right edge to be cropped.  | 
| image\$1y | Integer | Required |  Placement of the top edge of the overlay relative to the vertical axis for the video frame, in pixels. 0 is the top edge of the frame. When creating an event, cannot be omitted. Take note of the height of the overlay and make sure that the position of the top edge of the overlay does not cause the bottom edge to be cropped.  | 
| layer | Integer | Required |  A number from 0 to 7 to specify the Z order of the inserted overlay. “Z order” means that overlays with higher values of layer will be inserted on top of overlays with lower values of layer. Must always be specified. In the XML for modifying a static overlay at runtime, if the XML has more than one image container, then each layer tag must have a different value. So each overlay must be in its own layer.  | 
| opacity | Integer | Optional Default: 50 | The opacity of the overlay, as a number from 0 to 100. 0 is transparent. 100 is fully opaque. When creating an event, cannot be omitted. | 
| start\$1time | String |  Optional Default: beginning of the event  | The start time for the overlay. Specify the start time in one of the formats discussed below this table. | 

**Start time formats******

**Option 1**: Timecode format (HH:MM:SS:FF). The overlay start is determined by comparing the specified start to the appropriate timecode. 
+ If the overlay is specified in the Input section: The start time for the static overlay will be compared to the input timecode (the timecode for a given input). The source for the input timecode is specified separately for each input (Input > Timecode Source field). The input timecode is calculated as follows: 
  + If Timecode Source is Embedded: The timecode associated with each frame is extracted from the timecode carried with the input media. Note that each input will have its own timecode and the timecode may not align well from one input to another. 
  + If Timecode Source field is Start at 0: The timecode of the first frame of the input is 00:00:00:00 and the timecode counts up with each successive frame. The timecode starts over with each input. 
  + If Timecode Source field is System Clock or Local System Clock (AWS Elemental Live only): The timecode of each frame in the input is the system time at which the frame is decoded. 
+ If the overlay is specified in the Global Processor section: The overlay start is compared to the output timecode (which is shared by all outputs). The source for the output timecode is specified for the entire event, in the Timecode Config > Source field. The output timecode is calculated as follows: 
  + If Source is Embedded: The timecode is extracted from the timecode carried with the input media. That timecode becomes the output timecode for the first transcoded frame. Then the output timecode counts up with each successive frame in the entire output. 
  + If Source is Start at 0: The output timecode for the first frame is 00:00:00:00 and then the output timecode counts up with each successive frame in the entire output. 
  + If Source is System Clock or Local System Clock (AWS Elemental Live only): The output timecode for the first frame is the system time at which the frame is decoded. Then the output timecode counts up with each successive frame in the entire output. 
  + If Source is Specified Start: The output timecode for the first frame is the time you specified when you selected this option as the timecode source. Then the output timecode counts up with each successive frame in the entire output. 
  + If Source is External Reference Connector (AWS Elemental Live only): The timecode is extracted from external LTC source. That timecode becomes the output timecode for the first transcoded frame. Then the output timecode counts up with each successive frame in the entire output. 
+ If the static overlay is specified in the Output section: The start time for the static overlay is calculated in the same way as a static overlay in the Global Processor section. 

**Option 2**: ISO 8601 UTC time with no dashes or colons. For example, 20160102T030405.678Z. In this case, the start time for every overlay (regardless of whether it is defined in the input, the global processor or the output) will be the UTC time. 

**Option 3**: Only when adding or modifying an overlay in a running event (not when creating an event or modifying a non-running event), set this tag to an empty string to set the start time to “now”. With this option, the start time is never exact. 

## Example
<a name="example-non-running"></a>

The following request creates an event with the name myLiveEvent and includes one static overlay to insert the file logo.bmp. The overlay is inserted directly inside the live\$1event, which means it will appear in all outputs.

```
POST http://198.51.100.22/live_events
```

```
<?xml version="1.0" encoding="UTF-8"?>
  <live_event>
    <name>myLiveEvent</name>
    ...
      <image_inserter>
        <enable_rest>true</enable_rest>
        <insertable_images>
          <insertable_image>
            <duration>30000</duration>
            <fade_in>10</fade_in>
            <fade_out>10</fade_out>
            <height>900</height>
            <left>300</left>
            <top>400</top>
            <layer>0</layer>
            <start_time>16:09:09:10</start_time>
            <width>800</width>
            <image_inserter_input>
              <uri>mnt/storage/logo.bmp</uri>
            </image_inserter_input>
          </insertable_image>
        </insertable_images>
      </image_inserter>
     ...
  </live_event>
```

# Modify static overlay on a running event
<a name="modify-static-overlay-on-a-running-event"></a>

In a running event, you can use the REST API to add more static overlays, modify the behavior of an existing static overlay, or delete an existing static overlay.

**Note**  
Commands sent during an event change the event XML. Therefore, if you export the XML and create a new event with it, the new event will have any overlays set up as they were set during the course of the event, not as they were when the event was created. 

## HTTP request and response
<a name="http-request-and-response-running"></a>

**HTTP URL - one input** 

To add, modify, or delete the static overlay in one input element.

```
POST http://<Live IP Address>/live_events/<id>/image_inserter/input/<input id> 
```

Where `<input id>` is the unique ID automatically assigned to this input when the event is created or when the input is added to the event. 

or: 

```
POST http://<Live IP Address>/live_events/<id>/image_inserter/input/by_label/<input label> 
```

Where `<input label>` is the input label you assigned when you created this event or created this input. Input labels are always optional.

**HTTP URL - all outputs** 

To add, modify, or delete the static overlay in all outputs.

```
POST http://<Live IP Address>/live_events/<id>/image_inserter 
```

**HTTP URL - one output** 

To add, modify, or delete the static overlay in one output.

```
POST http://<Live IP Address>/live_events/<id>/image_inserter/output/<output id>
```

Where `<output id>` is the unique ID automatically assigned to this output when the event is created.

**HTTP URL - outputs for one stream assembly** 

To add, modify, or delete the static overlay in the outputs associated with a given stream.

```
POST http://<Live IP Address>/live_events/<id>/image_inserter/output/by_stream/<stream id>
```

Where `<stream id>` is the `<ID>` automatically assigned to this stream when the event is created. The ID can change while the event is running (for example, if another stream is deleted), so you may need to obtain the current ID before sending this command.

**Body of request ** 

XML content consisting of: 
+ One or more image\$1inserter elements that each contains:
  + 1 to 8 <image> elements that each contains the tags in the table in the section [Create or modify a non-running event with static graphic overlay](create-or-modify-a-non-running-event-with-static-graphic-overlay.md).

For information about the tags to include for different actions, see [Types of changes](step-c-manage-overlays-on-a-running-event.md#static-overlay-types-of-changes).

**Response** 

The response repeats back the data that you posted with `<ID>` tags for `image_inserter` and each overlay. If the event is not running, the message “Event <ID> is not running” is returned.

## Example
<a name="example-running-event"></a>

The following request modifies the overlays in the event with the ID 16. It modifies the start time on the existing overlay in layer 3.

It also adds one overlay (in layer 4); if an overlay already exists in layer 4, that overlay is replaced with the new overlay (even if that overlay is currently running). If an overlay does not exist in layer 4, the overlay is added.

```
POST http://198.51.100.22/live_events/16/image_inserter
```

```
<?xml version="1.0" encoding="UTF-8"?>
  <image_inserter>
    <image>
      <activate>true</activate>
      <layer>3</layer>
      <start_time>17:09:09:10</start_time>
    </image>
    <image>
      <activate>true</activate>
      <duration>30000</duration>
      <fade_in>10</fade_in>
      <fade_out>10</fade_out>
      <height>900</height>
      <left>300</left>
      <top>400</top>
      <layer>4</layer>
      <start_time>16:09:09:10</start_time>
      <width>800</width>
      <image_inserter_input>
        <uri>mnt/storage/logo.bmp</uri>
      </image_inserter_input>
    </image>
  </image_inserter>
```