> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/cloud-playout-api/channel-overlays/add-overlay-to-cloud-playout-channel/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/_mcp/server.

# Add an overlay to a channel

POST https://api.fastpix.com/v1/cloud-playout/channels/{channelId}/overlays
Content-Type: application/json

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.


Reference: https://fastpix.com/docs/cloud-playout-api/channel-overlays/add-overlay-to-cloud-playout-channel

## Authentication

- `Authorization` header (basic auth, required) — 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

## Request

### Path parameters

- `channelId` (string, required) — The unique identifier of the channel the overlay is placed on.

### Body (application/json)

This endpoint expects a CloudPlayoutChannelOverlayRequest.

- `overlayId` (string, required) — 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.
- `startTime` (string, required) — 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.
- `duration` (integer, optional) — 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.
- `untilChannelEnd` (boolean, optional) — 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.
- `customResolution` (boolean, optional) — 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.
- `width` (integer, optional) — The width of the overlay in pixels. Required when `customResolution` is true, and must not exceed the channel's own width.
- `height` (integer, optional) — The height of the overlay in pixels. Required when `customResolution` is true, and must not exceed the channel's own height.
- `position` (boolean, optional) — 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.
- `positionX` (integer, optional) — The distance of the overlay's left edge from the left edge of the frame, in pixels. Required when `position` is true.
- `positionY` (integer, optional) — The distance of the overlay's top edge from the top edge of the frame, in pixels. Required when `position` is true.
- `opacity` (integer, optional) — How opaque the overlay is, from 1 to 100. Defaults to 100. For dynamic overlays it stays at 100.
- `repeat` (CloudPlayoutOverlayRepeat, optional) — Optional recurrence for a `static` overlay placement. Without it the overlay stays on air for the whole placement window.

## Response

### 200

Overlay added to the channel successfully

- `success` (boolean, optional) — Shows the request status. Returns true for success and false for failure.
- `data` (CloudPlayoutChannelOverlayResponseData, optional) — The overlay that was placed on a loop channel, or the overlays that were placed on a schedule channel.

## Types

### CloudPlayoutOverlayRepeat

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

- `everySeconds` (integer, required) — How often the overlay comes back on air, in seconds, measured from one appearance to the next and anchored at `startTime`.
- `showForSeconds` (integer, required) — How long the overlay stays on air each time, in seconds. It must be shorter than `everySeconds`. The last appearance is cut short at the end of the placement window rather than dropped.

### CloudPlayoutChannelOverlayResponseData

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

### CloudPlayoutChannelOverlay

An overlay placed on a Cloud Playout channel.

- `id` (string, optional) — The unique identifier FastPix assigns to the placement. Use this identifier when you update or remove the overlay from the channel.
- `overlayId` (string, optional) — The unique identifier of the overlay that was placed.
- `channelId` (string, optional) — The unique identifier of the channel the overlay is placed on.
- `name` (string, optional) — The name given to the overlay.
- `type` (enum, optional) — The kind of overlay. A `static` overlay shows a fixed image or video, and a `dynamic` overlay renders content that changes while it is on air.
  - Allowed values: `static`, `dynamic`
- `overlayLayoutType` (string, optional) — The layout the overlay was created with, such as a logo, an aston, or an L-band.
- `overlayImageURL` (string, optional) — A URL to the overlay's source file.
- `startTime` (datetime, optional) — When the overlay comes on air, defined as a localDateTime (UTC Time).
- `endTime` (datetime, optional) — When the overlay goes off air, defined as a localDateTime (UTC Time).
- `duration` (string, optional) — How long the overlay stays on air, formatted as `HH:MM:SS`.
- `untilChannelEnd` (boolean, optional) — Whether the overlay stays on air until the channel's end time.
- `customResolution` (boolean, optional) — Whether the overlay was given its own width and height.
- `width` (integer, optional) — The width of the overlay in pixels.
- `height` (integer, optional) — The height of the overlay in pixels.
- `position` (boolean, optional) — Whether the overlay was given its own position.
- `positionX` (integer, optional) — The distance of the overlay's left edge from the left edge of the frame, in pixels.
- `positionY` (integer, optional) — The distance of the overlay's top edge from the top edge of the frame, in pixels.
- `opacity` (integer, optional) — How opaque the overlay is, from 1 to 100.

## Examples

**Request**

```json
{
  "overlayId": "2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16",
  "startTime": "2026-09-02T18:00:00",
  "duration": 600,
  "position": true,
  "positionX": 40,
  "positionY": 40,
  "opacity": 100
}
```

**Response**

```json
{
  "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
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays"

payload = {
    "overlayId": "2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16",
    "startTime": "2026-09-02T18:00:00",
    "duration": 600,
    "position": True,
    "positionX": 40,
    "positionY": 40,
    "opacity": 100
}
headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, auth=("<username>", "<password>"))

print(response.json())
```

```javascript
const url = 'https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays';
const credentials = btoa("<username>:<password>");

const options = {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: '{"overlayId":"2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16","startTime":"2026-09-02T18:00:00","duration":600,"position":true,"positionX":40,"positionY":40,"opacity":100}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays"

	payload := strings.NewReader("{\n  \"overlayId\": \"2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16\",\n  \"startTime\": \"2026-09-02T18:00:00\",\n  \"duration\": 600,\n  \"position\": true,\n  \"positionX\": 40,\n  \"positionY\": 40,\n  \"opacity\": 100\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.SetBasicAuth("<username>", "<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request.basic_auth("<username>", "<password>")
request["Content-Type"] = 'application/json'
request.body = "{\n  \"overlayId\": \"2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16\",\n  \"startTime\": \"2026-09-02T18:00:00\",\n  \"duration\": 600,\n  \"position\": true,\n  \"positionX\": 40,\n  \"positionY\": 40,\n  \"opacity\": 100\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays")
  .basicAuth("<username>", "<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"overlayId\": \"2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16\",\n  \"startTime\": \"2026-09-02T18:00:00\",\n  \"duration\": 600,\n  \"position\": true,\n  \"positionX\": 40,\n  \"positionY\": 40,\n  \"opacity\": 100\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays', [
  'body' => '{
  "overlayId": "2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16",
  "startTime": "2026-09-02T18:00:00",
  "duration": 600,
  "position": true,
  "positionX": 40,
  "positionY": 40,
  "opacity": 100
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
    'auth' => ['<username>', '<password>'],
]);

echo $response->getBody();
```

```csharp
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays");
client.Authenticator = new HttpBasicAuthenticator("<username>", "<password>");
var request = new RestRequest(Method.POST);

request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"overlayId\": \"2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16\",\n  \"startTime\": \"2026-09-02T18:00:00\",\n  \"duration\": 600,\n  \"position\": true,\n  \"positionX\": 40,\n  \"positionY\": 40,\n  \"opacity\": 100\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let credentials = Data("<username>:<password>".utf8).base64EncodedString()

let headers = [
  "Authorization": "Basic \(credentials)",
  "Content-Type": "application/json"
]
let parameters = [
  "overlayId": "2f6c1d84-9b3a-4d0e-8f21-5c7e3a9b4d16",
  "startTime": "2026-09-02T18:00:00",
  "duration": 600,
  "position": true,
  "positionX": 40,
  "positionY": 40,
  "opacity": 100
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

> The single API stack for video: upload, encode, stream, secure, and analyze video at any scale. Explore guides, API references, and SDKs.