Watermark processing

Watermark workflow

Use the same quote → submit → poll → result flow as other tasks. The tool catalog includes watermark-find (find candidates), watermark-mask (track and preview a mask), and the removal tools available for the source kind. Read the catalog’s parameter choices before submitting. Candidate marks require review; saving them does not itself create a processing task.

1. Run watermark-find on the chosen source version and read watermarkFind from its result.
2. Review the suggested regions and save the confirmed marks on that version.
3. Quote and submit watermark-mask with the confirmed regions to preview tracking.
4. Inspect maskPreviewUrl and the analysis report, then submit the applicable removal tool with the same source version and confirmed parameters.

Save watermark marks

This replaces all marks on the specified version. Coordinates are normalized from 0 to 1 with the top-left as the origin; x + width and y + height must stay within 1. timeMs identifies a video frame in milliseconds; omit it for a fixed position over the whole clip. Marks with the same objectId describe the same watermark.

positive marks indicate a watermark; negative excludes an area; absent marks an interval without that object; suggested is an unconfirmed candidate and is not executed. Pass timeMs for negative/absent/suggested marks, and objectId for absent/suggested marks. endMs, when used, must be at least timeMs. Use at most 64 total marks and eight objects, with at most 32 positive regions for processing. Sending regions: [] clears all marks; omitting objects clears their names.

The example saves a confirmed rectangle for the first frame. This persists annotations only: pass your confirmed regions in the task’s params when requesting tracking or removal. It does not automatically start or configure a task.

PUT/api/v1/assets/{assetId}/versions/{versionId}/watermark-marks

Bearer API KeyScope: writeSuccess: 204

Path, query and headers

Parameter	Location	Type & constraints
assetId required	path	string
versionId required	path	string

Request body fields · application/json

objectsobject[]optional

maxItems: 8

Expand fields / variants

namestringrequired

minLength: 1 · maxLength: 24

objectIdinteger · int64required

minimum: 0 · maximum: 7

regionsobject[]required

maxItems: 64

Expand fields / variants

colorstringoptional

pattern: "^#[0-9a-fA-F]{6}$"

endMsinteger · int64optional

minimum: 0

heightnumber · doublerequired

minimum: 0 · maximum: 1

kind"positive" | "negative" | "absent" | "suggested"optional

objectIdinteger · int64optional

minimum: 0 · maximum: 7

strokesobject[]optional

maxItems: 64

Expand fields / variants

pointsnumber · double[][]required

minItems: 1 · maxItems: 4000

Expand fields / variants

number · double

radiusnumber · doublerequired

minimum: 0 · maximum: 0.25

timeMsinteger · int64optional

minimum: 0

widthnumber · doublerequired

minimum: 0 · maximum: 1

xnumber · doublerequired

minimum: 0 · maximum: 1

ynumber · doublerequired

minimum: 0 · maximum: 1

Request example

cURL

curl --include --fail-with-body --silent --show-error --max-time 60 \
  --request PUT 'https://app.berserkapi.com/api/v1/assets/ASSET_ID/versions/VERSION_ID/watermark-marks' \
  --header "Authorization: Bearer $GLACIER_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "regions": [
    {
      "x": 0.7,
      "y": 0.05,
      "width": 0.2,
      "height": 0.1,
      "timeMs": 0,
      "objectId": 0,
      "kind": "positive"
    }
  ],
  "objects": [
    {
      "id": 0,
      "name": "Logo"
    }
  ]
}'

Node.js

// Node.js 22+; save as example.mjs, then: node example.mjs
const key = process.env.GLACIER_API_KEY;
if (!key) throw new Error('Set GLACIER_API_KEY');
const response = await fetch('https://app.berserkapi.com/api/v1/assets/ASSET_ID/versions/VERSION_ID/watermark-marks', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${key}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "regions": [
    {
      "x": 0.7,
      "y": 0.05,
      "width": 0.2,
      "height": 0.1,
      "timeMs": 0,
      "objectId": 0,
      "kind": "positive"
    }
  ],
  "objects": [
    {
      "id": 0,
      "name": "Logo"
    }
  ]
}),
  signal: AbortSignal.timeout(60_000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
console.log(response.status, text);

Python

# Python 3.10+; standard library; python example.py
import os
import urllib.request
import urllib.error

headers = {"Authorization": "Bearer " + os.environ["GLACIER_API_KEY"]}
headers["Content-Type"] = "application/json"
request = urllib.request.Request(
    "https://app.berserkapi.com/api/v1/assets/ASSET_ID/versions/VERSION_ID/watermark-marks",
    method="PUT",
    headers=headers,
    data="""
{
  "regions": [
    {
      "x": 0.7,
      "y": 0.05,
      "width": 0.2,
      "height": 0.1,
      "timeMs": 0,
      "objectId": 0,
      "kind": "positive"
    }
  ],
  "objects": [
    {
      "id": 0,
      "name": "Logo"
    }
  ]
}
""".encode("utf-8"),
)
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        print(response.status, response.read().decode("utf-8"))
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8')}") from error

Go

// Go 1.22+; go run example.go
package main

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

func main() {
    key := os.Getenv("GLACIER_API_KEY")
    if key == "" { panic("Set GLACIER_API_KEY") }
    req, err := http.NewRequest("PUT", "https://app.berserkapi.com/api/v1/assets/ASSET_ID/versions/VERSION_ID/watermark-marks", strings.NewReader(`{
  "regions": [
    {
      "x": 0.7,
      "y": 0.05,
      "width": 0.2,
      "height": 0.1,
      "timeMs": 0,
      "objectId": 0,
      "kind": "positive"
    }
  ],
  "objects": [
    {
      "id": 0,
      "name": "Logo"
    }
  ]
}`))
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + key)
    req.Header.Set("Content-Type", "application/json")
    client := &http.Client{Timeout: 60 * time.Second}
    res, err := client.Do(req)
    if err != nil { panic(err) }
    defer res.Body.Close()
    data, err := io.ReadAll(res.Body)
    if err != nil { panic(err) }
    if res.StatusCode >= 300 { panic(fmt.Sprintf("HTTP %d: %s", res.StatusCode, data)) }
    fmt.Println(res.StatusCode, string(data))
}

Rust

// cargo add reqwest@0.13 --features blocking
// Save in src/main.rs, then: cargo run
use std::{env, error::Error, time::Duration};

fn main() -> Result<(), Box<dyn Error>> {
    let client = reqwest::blocking::Client::builder()
        .timeout(Duration::from_secs(60)).build()?;
    let response = client.request(reqwest::Method::PUT, "https://app.berserkapi.com/api/v1/assets/ASSET_ID/versions/VERSION_ID/watermark-marks")
        .bearer_auth(env::var("GLACIER_API_KEY")?)
        .header("Content-Type", "application/json")
        .body(r#"{
  "regions": [
    {
      "x": 0.7,
      "y": 0.05,
      "width": 0.2,
      "height": 0.1,
      "timeMs": 0,
      "objectId": 0,
      "kind": "positive"
    }
  ],
  "objects": [
    {
      "id": 0,
      "name": "Logo"
    }
  ]
}"#)
        .send()?;
    let status = response.status();
    let text = response.text()?;
    if !status.is_success() { return Err(format!("HTTP {status}: {text}").into()); }
    println!("{status} {text}");
    Ok(())
}

Java

// Java 17+; save as Example.java, then: java Example.java
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import java.util.Objects;

class Example {
    public static void main(String[] args) throws Exception {
        var key = Objects.requireNonNull(System.getenv("GLACIER_API_KEY"));
        var client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).build();
        var request = HttpRequest.newBuilder(URI.create("https://app.berserkapi.com/api/v1/assets/ASSET_ID/versions/VERSION_ID/watermark-marks"))
            .timeout(Duration.ofSeconds(60))
            .header("Authorization", "Bearer " + key)
            .header("Content-Type", "application/json")
            .method("PUT", HttpRequest.BodyPublishers.ofString("""
{
  "regions": [
    {
      "x": 0.7,
      "y": 0.05,
      "width": 0.2,
      "height": 0.1,
      "timeMs": 0,
      "objectId": 0,
      "kind": "positive"
    }
  ],
  "objects": [
    {
      "id": 0,
      "name": "Logo"
    }
  ]
}
"""))
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300)
            throw new IllegalStateException("HTTP " + response.statusCode() + ": " + response.body());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

C#

// .NET 8+; dotnet new console; replace Program.cs; dotnet run
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var key = Environment.GetEnvironmentVariable("GLACIER_API_KEY")
    ?? throw new InvalidOperationException("Set GLACIER_API_KEY");
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
using var request = new HttpRequestMessage(new HttpMethod("PUT"), "https://app.berserkapi.com/api/v1/assets/ASSET_ID/versions/VERSION_ID/watermark-marks");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", key);
request.Content = new StringContent("""
{
  "regions": [
    {
      "x": 0.7,
      "y": 0.05,
      "width": 0.2,
      "height": 0.1,
      "timeMs": 0,
      "objectId": 0,
      "kind": "positive"
    }
  ],
  "objects": [
    {
      "id": 0,
      "name": "Logo"
    }
  ]
}
""", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"HTTP {(int)response.StatusCode}: {text}");
Console.WriteLine($"{(int)response.StatusCode} {text}");

Response fields · 204

No response body. Do not attempt to parse empty JSON.

Read detailed analysis

Use the analysis task ID or the watermarkAnalysisUrl returned with a result. This is an authenticated JSON API request, not a signed file download. Reports include objects, time intervals and regions that may need review. Use them together with the mask preview before removal.

GET/api/v1/tasks/{taskId}/watermark-analysis

Bearer API KeyScope: readSuccess: 200

Path, query and headers

Parameter	Location	Type & constraints
taskId required	path	string

Request example

cURL

curl --include --fail-with-body --silent --show-error --max-time 60 \
  --request GET 'https://app.berserkapi.com/api/v1/tasks/TASK_ID/watermark-analysis' \
  --header "Authorization: Bearer $GLACIER_API_KEY"

Node.js

// Node.js 22+; save as example.mjs, then: node example.mjs
const key = process.env.GLACIER_API_KEY;
if (!key) throw new Error('Set GLACIER_API_KEY');
const response = await fetch('https://app.berserkapi.com/api/v1/tasks/TASK_ID/watermark-analysis', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${key}`,
  },
  signal: AbortSignal.timeout(60_000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
console.log(response.status, text);

Python

# Python 3.10+; standard library; python example.py
import os
import urllib.request
import urllib.error

headers = {"Authorization": "Bearer " + os.environ["GLACIER_API_KEY"]}
request = urllib.request.Request(
    "https://app.berserkapi.com/api/v1/tasks/TASK_ID/watermark-analysis",
    method="GET",
    headers=headers,
)
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        print(response.status, response.read().decode("utf-8"))
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8')}") from error

Go

// Go 1.22+; go run example.go
package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

func main() {
    key := os.Getenv("GLACIER_API_KEY")
    if key == "" { panic("Set GLACIER_API_KEY") }
    req, err := http.NewRequest("GET", "https://app.berserkapi.com/api/v1/tasks/TASK_ID/watermark-analysis", nil)
    if err != nil { panic(err) }
    req.Header.Set("Authorization", "Bearer " + key)
    client := &http.Client{Timeout: 60 * time.Second}
    res, err := client.Do(req)
    if err != nil { panic(err) }
    defer res.Body.Close()
    data, err := io.ReadAll(res.Body)
    if err != nil { panic(err) }
    if res.StatusCode >= 300 { panic(fmt.Sprintf("HTTP %d: %s", res.StatusCode, data)) }
    fmt.Println(res.StatusCode, string(data))
}

Rust

// cargo add reqwest@0.13 --features blocking
// Save in src/main.rs, then: cargo run
use std::{env, error::Error, time::Duration};

fn main() -> Result<(), Box<dyn Error>> {
    let client = reqwest::blocking::Client::builder()
        .timeout(Duration::from_secs(60)).build()?;
    let response = client.request(reqwest::Method::GET, "https://app.berserkapi.com/api/v1/tasks/TASK_ID/watermark-analysis")
        .bearer_auth(env::var("GLACIER_API_KEY")?)
        .send()?;
    let status = response.status();
    let text = response.text()?;
    if !status.is_success() { return Err(format!("HTTP {status}: {text}").into()); }
    println!("{status} {text}");
    Ok(())
}

Java

// Java 17+; save as Example.java, then: java Example.java
import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import java.util.Objects;

class Example {
    public static void main(String[] args) throws Exception {
        var key = Objects.requireNonNull(System.getenv("GLACIER_API_KEY"));
        var client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(30)).build();
        var request = HttpRequest.newBuilder(URI.create("https://app.berserkapi.com/api/v1/tasks/TASK_ID/watermark-analysis"))
            .timeout(Duration.ofSeconds(60))
            .header("Authorization", "Bearer " + key)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300)
            throw new IllegalStateException("HTTP " + response.statusCode() + ": " + response.body());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

C#

// .NET 8+; dotnet new console; replace Program.cs; dotnet run
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var key = Environment.GetEnvironmentVariable("GLACIER_API_KEY")
    ?? throw new InvalidOperationException("Set GLACIER_API_KEY");
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://app.berserkapi.com/api/v1/tasks/TASK_ID/watermark-analysis");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", key);
using var response = await client.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException($"HTTP {(int)response.StatusCode}: {text}");
Console.WriteLine($"{(int)response.StatusCode} {text}");

Response fields · 200

detectionVersionstringrequired

framesinteger · int64required

heightinteger · int64required

marksHashstringrequired

objectsobject[]required

Expand fields / variants

colorobjectrequired

Expand fields / variants

alphanumber · doublerequired

rgbinteger · int64[]required

minItems: 3 · maxItems: 3

Expand fields / variants

integer · int64

samplesinteger · int64required

intervalsobject[]required

Expand fields / variants

endFrameinteger · int64required

endMsinteger · int64required

reasonsstring[]required

Expand fields / variants

string

sourcestringrequired

startFrameinteger · int64required

startMsinteger · int64required

state"present" | "bridge" | "manual" | "uncertain" | "absent"required

namestringrequired

objectIdinteger | null · int64required

poseobject[]required

Expand fields / variants

detailstringrequired

okbooleanrequired

reasonstringrequired

sourcestringrequired

shapeobjectrequired

Expand fields / variants

qualitystringrequired

reasonstringrequired

policystringrequired

ratenumber · doublerequired

reviewobject[]required

Expand fields / variants

boxobjectrequired

Expand fields / variants

heightnumber · doublerequired

minimum: 0 · maximum: 1

widthnumber · doublerequired

minimum: 0 · maximum: 1

xnumber · doublerequired

minimum: 0 · maximum: 1

ynumber · doublerequired

minimum: 0 · maximum: 1

endFrameinteger · int64required

endMsinteger · int64required

namestringrequired

objectIdinteger | null · int64required

reasonstringrequired

scorenumber | null · doublerequired

startFrameinteger · int64required

startMsinteger · int64required

staticobject[]required

Expand fields / variants

namestringrequired

objectIdinteger | null · int64required

reasonstringrequired

shapestringrequired

versioninteger · int64required

widthinteger · int64required