> 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/update-cloud-playout-channel-overlay/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/_mcp/server.

# Update an overlay on a channel

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

This endpoint changes how an overlay already placed on a Cloud Playout channel looks, without removing and adding it again.

#### How it works

1. Make a PATCH request to this endpoint with the ID of the placement, which you can get from the get all overlays on a channel endpoint.

2. Send only the fields you want to change. At least one field is required.

3. The response returns the updated placement.

When the overlay runs is fixed once it is placed, so `startTime`, `duration` and `untilChannelEnd` cannot be changed here. To move a placement, remove it and add it again. Which overlay the placement uses is fixed too.

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.

Send `repeat` to change how often the overlay comes back on air, or `removeRepeat` set to true to stop it repeating and leave it on air for the whole placement. The two cannot be sent together.

What you can change depends on the overlay. A `dynamic` overlay renders its own layout, so size, position, opacity and `repeat` are not accepted for it. An aston or an L-band keeps the size and position the channel gives it, so only `repeat` can be changed on those.

#### Example

A broadcaster nudges its logo further from the frame edge and drops the opacity to 80 while a sponsor card is on air.


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

## 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 loop channel the overlay is placed on.
- `overlayConfigId` (string, required) — The unique identifier of the placement to update, as returned in the `id` field by the get all overlays on a channel endpoint.

### Body (application/json)

This endpoint expects a CloudPlayoutChannelOverlayUpdateRequest.

- `customResolution` (boolean, optional) — Set to true to give the overlay your own `width` and `height`. When it is false, `width` and `height` must be left out.
- `width` (integer, optional) — A new width for the overlay in pixels. Required when `customResolution` is true, and must not exceed the channel's own width.
- `height` (integer, optional) — A new height for 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, `positionX` and `positionY` must be left out.
- `positionX` (integer, optional) — A new distance of the overlay's left edge from the left edge of the frame, in pixels. Required when `position` is true.
- `positionY` (integer, optional) — A new distance of the overlay's top edge from the top edge of the frame, in pixels. Required when `position` is true.
- `opacity` (integer, optional) — A new opacity for the overlay, from 1 to 100.
- `repeat` (CloudPlayoutOverlayRepeat, optional) — Optional recurrence for a `static` overlay placement. Without it the overlay stays on air for the whole placement window.
- `removeRepeat` (boolean, optional) — Set to true to stop the overlay repeating and leave it on air for the whole placement. It cannot be sent together with `repeat`.

## Response

### 200

Overlay updated successfully

- `success` (boolean, optional) — Shows the request status. Returns true for success and false for failure.
- `data` (CloudPlayoutChannelOverlay, optional) — An overlay placed on a Cloud Playout 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.

### 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
{
  "position": true,
  "positionX": 60,
  "positionY": 60,
  "opacity": 80
}
```

**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",
    "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": 60,
    "positionY": 60,
    "opacity": 80
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays/5e8b2c31-7a49-4d62-b0f8-9c1e4a7d2b53"

payload = {
    "position": True,
    "positionX": 60,
    "positionY": 60,
    "opacity": 80
}
headers = {
    "Content-Type": "application/json"
}

response = requests.patch(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/5e8b2c31-7a49-4d62-b0f8-9c1e4a7d2b53';
const credentials = btoa("<username>:<password>");

const options = {
  method: 'PATCH',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: '{"position":true,"positionX":60,"positionY":60,"opacity":80}'
};

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/5e8b2c31-7a49-4d62-b0f8-9c1e4a7d2b53"

	payload := strings.NewReader("{\n  \"position\": true,\n  \"positionX\": 60,\n  \"positionY\": 60,\n  \"opacity\": 80\n}")

	req, _ := http.NewRequest("PATCH", 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/5e8b2c31-7a49-4d62-b0f8-9c1e4a7d2b53")

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

request = Net::HTTP::Patch.new(url)
request.basic_auth("<username>", "<password>")
request["Content-Type"] = 'application/json'
request.body = "{\n  \"position\": true,\n  \"positionX\": 60,\n  \"positionY\": 60,\n  \"opacity\": 80\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.patch("https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays/5e8b2c31-7a49-4d62-b0f8-9c1e4a7d2b53")
  .basicAuth("<username>", "<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"position\": true,\n  \"positionX\": 60,\n  \"positionY\": 60,\n  \"opacity\": 80\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.fastpix.com/v1/cloud-playout/channels/cc99cae6-56b4-46ab-9f4a-8b2462d8137c/overlays/5e8b2c31-7a49-4d62-b0f8-9c1e4a7d2b53', [
  'body' => '{
  "position": true,
  "positionX": 60,
  "positionY": 60,
  "opacity": 80
}',
  '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/5e8b2c31-7a49-4d62-b0f8-9c1e4a7d2b53");
client.Authenticator = new HttpBasicAuthenticator("<username>", "<password>");
var request = new RestRequest(Method.PATCH);

request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"position\": true,\n  \"positionX\": 60,\n  \"positionY\": 60,\n  \"opacity\": 80\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 = [
  "position": true,
  "positionX": 60,
  "positionY": 60,
  "opacity": 80
] 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/5e8b2c31-7a49-4d62-b0f8-9c1e4a7d2b53")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
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.