Watermarks

Watermark configuration takes effect on both the original stream and the transcoded stream.

Create watermark templates

Creates watermark templates for the specified entry point.

HTTP request

PATCH https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/settings/watermark

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.

Request body

The request body is in the JSON Object type, and contains the following fields:

Field	Type	Description
`watermarkSet`	JSON Array of WaterMark	Required. Watermark configuration sets. You can add a maximum of five configuration sets.

HTTP response

If the returned HTTP status code is 200, the request is successful.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status codes for possible reasons.

Example

Request line

PATCH https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/settings/watermark HTTP/1.1

Request body

{
    "waterMarkSet": [
        {
            "url": "http://pngimg.com/uploads/egg/egg_PNG40777.png",
            "x": 0,
            "y": 0,
            "width": 200,
            "height": 200,
            "zOrder": 2
        },
        {
            "url": "http://pngimg.com/uploads/egg/egg_PNG40777.png",
            "x": 0,
            "y": 0,
            "width": 300,
            "height": 300,
            "zOrder": 3
        }
    ]
}

Response line

HTTP/1.1 200 OK

List watermark templates

Lists the watermark templates available for the specified entry point.

HTTP request

GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/settings/watermark

Path parameter

Parameter	Type	Description
`appid`	String	Required. The App ID retrieved from Agora Console.
`entry_point`	String	Required. The entry point name.

HTTP response

If the returned HTTP status code is 200, the request is successful. The response body contains the following fields:

Field	Type	Description
`watermarkSet`	JSON Array of WaterMark	The list of watermark templates.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status codes for possible reasons.

Example

Request line

GET https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/settings/watermark HTTP/1.1

Request body

{
    "waterMarkSet": [
        {
            "url": "http://pngimg.com/uploads/egg/egg_PNG40777.png",
            "x": 0,
            "y": 0,
            "width": 200,
            "height": 200,
            "zOrder": 2
        },
        {
            "url": "http://pngimg.com/uploads/egg/egg_PNG40777.png",
            "x": 0,
            "y": 0,
            "width": 300,
            "height": 300,
            "zOrder": 3
        }
    ]
}

Response line

HTTP/1.1 200 OK

Data type

WaterMark

Watermark configuration parameters, including the following fields:

Field	Type	Description
`url`	String	Required. The URL of the watermark image. Only PNG files are supported. To easily set different watermarks for different entry points or live streams, you can use the following parameters in the URL: `{entry_point}`: This parameter is replaced with the specified entry point. `{stream_name}`: This parameter is replaced with the specified stream name.
`x`	Integer	Required. The x-coordinate of the watermark. The value range is [0,1920].
`y`	Integer	Required. The y-coordinate of the watermark. The value range is [0,1920].
`width`	Integer	Required. The width (pixels) of the watermark image. The value range is [0,1920].
`height`	Integer	Required. The height (pixels) of the watermark image. The value range is [0,1920].

HTTP status codes

Status code	Description
200	The request succeeds.
400	The parameter is invalid, for example the `appid` or the `entry_point` is empty, or the `region` parameter value is invalid.
401	Unauthorized (the customer ID and the customer secret do not match).
404	The server cannot find the resource according to the request, which means the requested entry point does not exist or the requested URI path is invalid.
500	An internal error occurs in the server, so the server is not able to complete the request.
504	An internal error occurs in the server. The gateway or the proxy server did not receive a timely request from the remote server.