Add an overlay to a channel | FastPix Developer Documentation

curl -X POST https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays \
     -H "Content-Type: application/json" \
     -u "<username>:<password>" \
     -d '{
  "overlayId": "2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16",
  "startTime": "2026-09-02T18:00:00",
  "duration": 600,
  "position": true,
  "positionX": 40,
  "positionY": 40,
  "opacity": 100
}'

{
  "success": true,
  "data": {
    "id": "5e8b2c31-7a49-4d62-b0f8-9c1e4a7d2b53",
    "overlayId": "2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16",
    "channelId": "cc99cae6-56b4-46ab-9f4a-8b2462d8137c",
    "name": "Channel logo",
    "type": "static",
    "overlayLayoutType": "logo",
    "overlayImageURL": "https://images.fastpix.com/2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16/overlay.png",
    "startTime": "2026-09-02T18:00:00Z",
    "endTime": "2026-09-02T18:10:00Z",
    "duration": "00:10:00",
    "untilChannelEnd": false,
    "customResolution": false,
    "width": 100,
    "height": 100,
    "position": true,
    "positionX": 40,
    "positionY": 40,
    "opacity": 100
  }
}

This endpoint places an overlay on a Cloud Playout channel, so the channel renders it onto the output while it is on air. Loop and schedule channels take the same body.

Create the overlay itself first with the create an overlay endpoint, and use the ID it returns here.

Placing an overlay

Send a single overlayId together with a startTime, and either a duration in seconds or untilChannelEnd set to true to keep the overlay on air until the channel ends. The overlay’s whole run must sit inside the channel’s own start and end times, so a placement that would end after the channel does is rejected.

By default the overlay keeps the size and position it was created with. Set customResolution to true to send your own width and height, and position to true to send your own positionX and positionY. The upper bounds come from the channel’s own resolution, so a 1080p channel accepts a width up to 1920 and a height up to 1080. opacity runs from 1 to 100.

Dynamic overlays render their own layout, so customResolution and position are not supported for them and opacity stays at 100.

Showing an overlay repeatedly

A static overlay can come back on air on a cycle instead of staying up for the whole placement. Send repeat with everySeconds and showForSeconds: the overlay is shown for showForSeconds every everySeconds, measured from one appearance to the next and anchored at startTime. showForSeconds must be shorter than everySeconds, and the last appearance is cut short at the end of the placement window rather than dropped.

How many overlays can be on air at once

At most two static overlays can be on air at the same instant, and only one dynamic overlay. An aston and an L-band cannot be on air together, and while either is on air only a logo or a dynamic overlay can join it.

Example

A news channel places its logo in the top right corner for the whole broadcast, then adds an aston for the first ten minutes of the evening bulletin.

Authentication

AuthorizationBasic

FastPix APIs are secured with Basic Authentication. Use your Access Token ID as the username and Secret Key as the password in the Authorization header of each API request.

Username: Access Token ID
Password: Secret Key

Activate your FastPix account to generate your API credentials. See the guide here

Path parameters

channelIdstringRequiredformat: "uuid"

The unique identifier of the channel the overlay is placed on.

Request

This endpoint expects an object.

overlayIdstringRequiredformat: "uuid"

The unique identifier of the overlay to place, as returned by the create an overlay endpoint. It must belong to the same workspace as the channel.

startTimestringRequired

When the overlay comes on air, in yyyy-MM-dd'T'HH:mm:ss format and interpreted as UTC. It cannot be earlier than the channel's start time.

durationintegerOptional>=1

How long the overlay stays on air, in seconds. Required unless untilChannelEnd is true, in which case it must be left out. The overlay must finish before the channel's end time.

untilChannelEndbooleanOptional

Set to true to keep the overlay on air from startTime until the channel's end time. When it is true, duration must be left out.

customResolutionbooleanOptional

Set to true to give the overlay your own width and height. When it is false, the overlay keeps the size it was created with, and width and height must be left out. Not supported for dynamic overlays.

widthintegerOptional>=10

The width of the overlay in pixels. Required when customResolution is true, and must not exceed the channel's own width.

heightintegerOptional>=10

The height of the overlay in pixels. Required when customResolution is true, and must not exceed the channel's own height.

positionbooleanOptional

Set to true to give the overlay your own positionX and positionY. When it is false, the overlay keeps the position it was created with, and positionX and positionY must be left out. Not supported for dynamic overlays.

positionXintegerOptional>=0

The distance of the overlay's left edge from the left edge of the frame, in pixels. Required when position is true.

positionYintegerOptional>=0

The distance of the overlay's top edge from the top edge of the frame, in pixels. Required when position is true.

opacityintegerOptional1-100

How opaque the overlay is, from 1 to 100. Defaults to 100. For dynamic overlays it stays at 100.

repeatobjectOptional

Optional recurrence for a static overlay placement. Without it the overlay stays on air for the whole placement window.

Response

Overlay added to the channel successfully

successbooleanOptional

Shows the request status. Returns true for success and false for failure.

dataobject or list of objectsOptional

The overlay that was placed on a loop channel, or the overlays that were placed on a schedule channel.