> ## Documentation Index
> Fetch the complete documentation index at: https://gcore.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create overlays
> "Overlay" is a live HTML widget, which rendered and inserted over the live stream.
There are can be more that 1 overlay over a stream, which are small or stretched over full frame. Overlays can have transparent areas. Frequency of update is 1 FPS. Automatic size scaling for Adaptative Bitrate qualities is applied.
How to activate and use in simple steps:
- Activate feature on your account, ask the Support Team
- Set “`html_overlay`” attribute to "true" for a stream
- Set array of overlays
- Start or restart your stream again
- Enjoy :-)
For the first time an overlay should be enabled **before** start pushing of a live stream. If you are pushing the stream already (stream is alive and you are activating overlay for the first time), then overlay will become active after restart pushing.
Once you activate the overlay for the stream for the first time, you can add, change, move, delete widgets on the fly even during a live stream with no affection on a result stream.
Tech limits:
- Max original stream resolution = FullHD.
- It is necessary that all widgets must fit into the original frame of the source stream (width x height). If one of the widgets does not fit into the original frame, for example, goes 1 pixel beyond the frame, then all widgets will be hidden.
- Attributes of overlays:
- url – should be valid http/https url
- 0 < width <= 1920
- 0 < height <= 1080
- 0 <= x < 1920
- 0 <= y < 1080
- stretch – stretch to full frame. Cannot be used with positioning attributes.
- HTML widget can be access by HTTP 80 or HTTPS 443 ports.
- HTML page code at the "url" link is read once when starting the stream only. For dynamically updating widgets, you must use either dynamic code via JavaScript or cause a page refresh via HTML meta tag .
- Widgets can contain scripts, but they must be lightweight and using small amount memory, CPU, and bandwidth. It is prohibited to run heavy scripts, create a heavy load on the network, or run other heavy modules. Such widgets can be stopped automatically, and the ability to insert widgets itself is banned.
- If feature is disabled, you will receive HTTP code: 422. Error text: Feature disabled. Contact support to enable.
Please, pay attention to the content of HTML widges you use. If you don't trust them, then you shouldn't use them, as their result will be displayed in live stream to all users.
**Will there be a widget in the recording?**
Right now overlay widgets are sent to the end viewer in the HLS/DASH streams, but are not recorded due to technical limitations. We are working to ensure that widgets remain in the recordings as well. Follow the news.
## OpenAPI
````yaml /api-reference/services_documented/streaming_api.yaml post /streaming/streams/{stream_id}/overlays
openapi: 3.1.0
info:
title: Gcore OpenAPI – Streaming API
description: >-
This OpenAPI is an aggregated OpenAPI specification that unifies all Gcore
products into a single file. It covers Cloud, CDN, DNS, WAAP, DDoS
Protection, Object Storage, Streaming, and FastEdge services.
version: '2026-05-11T15:10:30.328297+00:00'
servers:
- url: https://api.gcore.com
security:
- APIKey: []
tags:
- name: AI
x-displayName: AI
- name: Broadcasts
x-displayName: Broadcasts
- name: Directories
x-displayName: Directories
- name: Overlays
x-displayName: Overlays
- name: Players
x-displayName: Players
- name: Playlists
x-displayName: Playlists
- name: QualitySets
x-displayName: QualitySets
- name: Restreams
x-displayName: Restreams
- name: Streaming Statistics
x-displayName: Statistics
- name: Streams
x-displayName: Streams
- name: Subtitles
x-displayName: Subtitles
- name: Videos
x-displayName: Videos
paths:
/streaming/streams/{stream_id}/overlays:
post:
tags:
- Overlays
summary: Create overlays
description: >-
"Overlay" is a live HTML widget, which rendered and inserted over the
live stream.
There are can be more that 1 overlay over a stream, which are small or
stretched over full frame. Overlays can have transparent areas.
Frequency of update is 1 FPS. Automatic size scaling for Adaptative
Bitrate qualities is applied.
How to activate and use in simple steps:
- Activate feature on your account, ask the Support Team
- Set “`html_overlay`” attribute to "true" for a stream
- Set array of overlays
- Start or restart your stream again
- Enjoy :-)
For the first time an overlay should be enabled **before** start pushing
of a live stream. If you are pushing the stream already (stream is alive
and you are activating overlay for the first time), then overlay will
become active after restart pushing.
Once you activate the overlay for the stream for the first time, you can
add, change, move, delete widgets on the fly even during a live stream
with no affection on a result stream.
Tech limits:
- Max original stream resolution = FullHD.
- It is necessary that all widgets must fit into the original frame of
the source stream (width x height). If one of the widgets does not fit
into the original frame, for example, goes 1 pixel beyond the frame,
then all widgets will be hidden.
- Attributes of overlays:
- url – should be valid http/https url
- 0 < width <= 1920
- 0 < height <= 1080
- 0 <= x < 1920
- 0 <= y < 1080
- stretch – stretch to full frame. Cannot be used with positioning
attributes.
- HTML widget can be access by HTTP 80 or HTTPS 443 ports.
- HTML page code at the "url" link is read once when starting the stream
only. For dynamically updating widgets, you must use either dynamic code
via JavaScript or cause a page refresh via HTML meta tag .
- Widgets can contain scripts, but they must be lightweight and using
small amount memory, CPU, and bandwidth. It is prohibited to run heavy
scripts, create a heavy load on the network, or run other heavy modules.
Such widgets can be stopped automatically, and the ability to insert
widgets itself is banned.
- If feature is disabled, you will receive HTTP code: 422. Error text:
Feature disabled. Contact support to enable.
Please, pay attention to the content of HTML widges you use. If you
don't trust them, then you shouldn't use them, as their result will be
displayed in live stream to all users.
**Will there be a widget in the recording?**
Right now overlay widgets are sent to the end viewer in the HLS/DASH
streams, but are not recorded due to technical limitations. We are
working to ensure that widgets remain in the recordings as well. Follow
the news.
operationId: post_overlays
parameters:
- name: stream_id
in: path
description: Stream ID
required: true
schema:
type: integer
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/overlayBody'
required: false
responses:
'200':
description: Successful
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/overlayId'
'400':
description: One or more parameters were specified incorrectly, check the request
content:
application/json:
schema:
$ref: '#/components/schemas/badrequest'
'422':
description: >-
This is advanced functionality; to enable it, contact your manager
or the Support Team.
content:
application/json:
schema:
$ref: '#/components/schemas/upgraderequired'
x-codeSamples:
- lang: Python
source: |-
import os
from gcore import Gcore
client = Gcore(
api_key=os.environ.get("GCORE_API_KEY"), # This is the default and can be omitted
)
overlays = client.streaming.streams.overlays.create(
stream_id=0,
)
print(overlays)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/G-Core/gcore-go\"\n\t\"github.com/G-Core/gcore-go/option\"\n\t\"github.com/G-Core/gcore-go/streaming\"\n)\n\nfunc main() {\n\tclient := gcore.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\toverlays, err := client.Streaming.Streams.Overlays.New(\n\t\tcontext.TODO(),\n\t\t0,\n\t\tstreaming.StreamOverlayNewParams{},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", overlays)\n}\n"
components:
schemas:
overlayBody:
allOf:
- $ref: '#/components/schemas/overlayBase'
- required:
- url
example:
url: http://domain.com/myoverlay1.html
width: 120
height: 40
x: 30
'y': 30
stretch: false
overlayId:
allOf:
- $ref: '#/components/schemas/overlayBase'
- required:
- id
- url
- stream_id
- created_at
- updated_at
properties:
id:
type: integer
description: ID of the overlay
stream_id:
type: integer
description: ID of a stream to which it is attached
created_at:
type: string
description: Datetime of creation in ISO 8601
updated_at:
type: string
description: Datetime of last update in ISO 8601
example:
id: 1
stream_id: 12345
url: http://domain.com/myoverlay1.html
width: 120
height: 40
x: 30
'y': 30
stretch: false
created_at: '2023-09-20T00:01:01.000Z'
updated_at: '2023-10-01T12:01:01.000Z'
badrequest:
type: object
properties:
status:
type: integer
description: Error number
error:
type: string
description: Error message
example:
status: 400
error: >-
Bad Request response status code indicates that the server cannot or
will not process the request due to something that is perceived to be
a client error (for example, malformed request syntax, invalid request
message framing, or deceptive request routing).
upgraderequired:
type: object
properties:
error:
type: string
description: >-
This is advanced functionality; to enable it, contact your manager
or support service.
example:
error: Feature is disabled. Contact support to enable.
overlayBase:
type: object
properties:
url:
type: string
description: Valid http/https URL to an HTML page/widget
width:
type: integer
default: null
description: Width of the widget
height:
type: integer
default: null
description: Height of the widget
x:
type: integer
default: null
description: Coordinate of left upper corner
'y':
type: integer
default: null
description: Coordinate of left upper corner
stretch:
type: boolean
default: false
description: >-
Switch of auto scaling the widget. Must not be used as "true"
simultaneously with the coordinate installation method (w, h, x, y).
securitySchemes:
APIKey:
description: >-
API key for authentication. Make sure to include the word `apikey`,
followed by a single space and then your token.
Example: `apikey 1234$abcdef`
type: apiKey
in: header
name: Authorization
````