Watermark API

Add watermarks or stamps to PDF documents, images or videos.

API Documentation

Use Text or Images as Watermark

The CloudConvert API allows to use both dynamic texts or PNG images as watermark. A typical use case is to add your company name or logo to files. You can find some examples below.

Add Watermarks to PDFs

The watermark can be either placed above (default) or below the text of your PDF document. You can define the watermark position and also only select specific pages. Check out the API docs for all available parameters.

Add Watermarks to Images

CloudConvert supports nearly any image format such as PNG, JPG, GIF and many more. You can customize the size, position, opacity, margin and rotation of the watermark.

Add Watermarks to Videos

Adding a watermark to a video requires re-encoding the video. CloudConvert automatically selects reasonable codec settings to avoid any loss in quality. However, this is fully customizable and you can set your own encoding settings if you wish so.

Async or Sync

By default, the CloudConvert API converts your files asynchronously and we notify you via webhooks when we are done. Depending on your needs there is also a synchronous API to convert files on-the-fly.

Storage Integration

CloudConvert directly fetches the input files from your object storage and then stores the output file at the same place. We are integrated with your existing and trusted storage provider, such as S3, Azure, Google Cloud or many others.

Custom Workflows

Our API uses the concept of Jobs and allows to do multiple operations with one single API call. For example, it is possible to convert the same file to multiple output formats, adding a watermark and creating a thumbnail with one single Job!

Developer Friendly

Our extensive API Documentation helps to get you started quickly. There is a Job Builder which generates ready-to-use request payloads and code snippets for you. We do provide free and timely support, directly from the builders of CloudConvert.

Raw Request PHP node.js Ruby Python Java .NET

Adding Watermark Texts

Watermark Text
POST https://sync.api.cloudconvert.com/v2/jobs
{
  "tasks": {
    "import-file": {
      "operation": "import/url",
      "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
    },
    "add-watermark": {
      "operation": "watermark",
      "input": [
        "import-file"
      ],
      "input_format": "pdf",
      "layer": "above",
      "text": "Top Secret",
      "font_size": 100,
      "font_color": "#ff0400",
      "font_name": "Helvetica Bold",
      "position_vertical": "center",
      "position_horizontal": "center",
      "opacity": 50,
      "rotation": -45
    },
    "export-watermarked-file": {
      "operation": "export/url",
      "input": [
        "add-watermark"
      ]
    }
  },
  "redirect": true
}
<?php
$job = (new Job())
    ->addTask(
        (new Task('import/url', 'import-file'))
            ->set('url', 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf')
    )
    ->addTask(
        (new Task('watermark', 'add-watermark'))
            ->set('input', 'import-file')
            ->set('input_format', 'pdf')
            ->set('layer', 'above')
            ->set('text', 'Top Secret')
            ->set('font_size', 100)
            ->set('font_color', '#ff0400')
            ->set('font_name', 'Helvetica Bold')
            ->set('position_vertical', 'center')
            ->set('position_horizontal', 'center')
            ->set('opacity', 50)
            ->set('rotation', -4)
    )
    ->addTask(
        (new Task('export/url', 'export-watermarked-file'))
            ->set('input', 'add-watermark')
    );

$cloudconvert->jobs()->create($job);
let exampleJob = await cloudConvert.jobs.create({
    "tasks": {
        "import-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "add-watermark": {
            "operation": "watermark",
            "input": [
                "import-file"
            ],
            "input_format": "pdf",
            "layer": "above",
            "text": "Top Secret",
            "font_size": 100,
            "font_color": "#ff0400",
            "font_name": "Helvetica Bold",
            "position_vertical": "center",
            "position_horizontal": "center",
            "opacity": 50,
            "rotation": -45
        },
        "export-watermarked-file": {
            "operation": "export/url",
            "input": [
                "add-watermark"
            ]
        }
    }
});

job = await cloudConvert.jobs.wait(job.id);
job = cloudconvert.jobs.create({
  tasks: [
      {
        name: "imprt-file",
        operation: "import/url",
        url: "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
      },
      {
        name: "add-watermark",
        operation: "watermark",
        input: [
          "import-file"
        ],
        input_format: "pdf",
        layer: "above",
        text: "Top Secret",
        font_size: 100,
        font_color: "#ff0400",
        font_name: "Helvetica Bold",
        position_vertical: "center",
        position_horizontal: "center",
        opacity: 50,
        rotation: -45
      },
      {
        name: "export-watermarked-file",
        operation: "export/url",
        input: [
          "add-watermark"
        ]
      }
  ]
})
job = cloudconvert.Job.create(payload={
     "tasks": {
        "import-file": {
          "operation": "import/url",
          "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "add-watermark": {
          "operation": "watermark",
          "input": [
            "import-file"
          ],
          "input_format": "pdf",
          "layer": "above",
          "text": "Top Secret",
          "font_size": 100,
          "font_color": "#ff0400",
          "font_name": "Helvetica Bold",
          "position_vertical": "center",
          "position_horizontal": "center",
          "opacity": 50,
          "rotation": -45
        },
        "export-watermarked-file": {
          "operation": "export/url",
          "input": [
            "add-watermark"
          ]
        }
     }
 })
final JobResponse createJobResponse = cloudConvertClient.jobs().create(
    ImmutableMap.of(
        "import-file",
            new UrlImportRequest()
                .setUrl("https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"),
        "add-watermark",
            new AddWatermarkTaskRequest()
                .setInput("import-file")
                .setInputFormat("pdf"),
                .set("layer", "above"),
                .set( "text", "Top Secret")
                .set("font_size", 100)
                .set("font_color", "#ff0400")
                .set("font_name", "Helvetica Bold")
                .set("position_vertical", "center")
                .set("position_horizontal", "center")
                .set("opacity", 50)
                .set("rotation", -45)
        "export-watermarked-file",
            new UrlExportRequest()
                .setInput("add-watermark")
    )
).getBody();
var job = await CloudConvert.CreateJobAsync(new JobCreateRequest
      {
        Tasks = new
        {
          import-file = new ImportUrlCreateRequest
          {
            Url = "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
          },
          add-watermark = new WatermarkCreateRequest
          {
            Input = "import-file",
            Input_Format = "pdf",
            Options = new Dictionary<string, object> {
                          { "layer": "above" },
                          { "text": "Top Secret" },
                          { "font_size": 100 },
                          { "font_color": "#ff0400" },
                          { "font_name": "Helvetica Bold" },
                          { "position_vertical": "center" },
                          { "position_horizontal": "center" },
                          { "opacity": 50 },
                          { "rotation": -45 }
                        }
          },
          export-watermarked-file = new ExportUrlCreateRequest
          {
            Input = "add-watermark"
          }
        }
      });

Adding Watermark Images

Watermark Image
POST https://api.cloudconvert.com/v2/jobs
{
  "tasks": {
    "import-file": {
      "operation": "import/url",
      "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
    },
    "import-logo": {
      "operation": "import/url",
      "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/logo.png"
    },
    "add-watermark": {
      "operation": "watermark",
      "input": [
        "import-file"
      ],
      "input_format": "pdf",
      "layer": "above",
      "image": [
        "import-logo"
      ],
      "image_width": 500,
      "position_vertical": "bottom",
      "position_horizontal": "right",
      "margin_vertical": 25,
      "margin_horizontal": 25,
      "opacity": 75
    },
    "export-watermarked-file": {
      "operation": "export/url",
      "input": [
        "add-watermark"
      ]
    }
  },
  "redirect": true
}
<?php
$job = (new Job())
    ->addTask(
        (new Task('import/url', 'import-file'))
            ->set('url', 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf')
    )
    ->addTask(
        (new Task('import/url', 'import-logo'))
            ->set('url', 'https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/logo.png')
    )
    ->addTask(
        (new Task('watermark', 'add-watermark'))
            ->set('input', 'import-file')
            ->set('input_format', 'pdf')
            ->set('layer', 'above')
            ->set('image', 'import-logo')
            ->set('image_width', 500)
            ->set('position_vertical', 'center')
            ->set('position_horizontal', 'center')
            ->set('margin_vertical', 25)
            ->set('margin_horizontal', 25)
            ->set('opacity', 75)
    )
    ->addTask(
        (new Task('export/url', 'export-watermarked-file'))
            ->set('input', 'add-watermark')
    );

$cloudconvert->jobs()->create($job);
let exampleJob = await cloudConvert.jobs.create({
    "tasks": {
        "import-file": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
        },
        "import-logo": {
            "operation": "import/url",
            "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/logo.png"
        },
        "add-watermark": {
            "operation": "watermark",
            "input": [
                "import-file"
            ],
            "input_format": "pdf",
            "layer": "above",
            "image": [
                "import-logo"
            ],
            "image_width": 500,
            "position_vertical": "bottom",
            "position_horizontal": "right",
            "margin_vertical": 25,
            "margin_horizontal": 25,
            "opacity": 75
        },
        "export-watermarked-file": {
            "operation": "export/url",
            "input": [
                "add-watermark"
            ]
        }
    }
});

job = await cloudConvert.jobs.wait(job.id);
job = cloudconvert.jobs.create({
  tasks: [
      {
        name: "imprt-file",
        operation: "import/url",
        url: "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
      },
      {
        name: "imprt-logo",
        operation: "import/url",
        url: "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/logo.png"
      },
      {
        name: "add-watermark",
        operation: "watermark",
        input: [
          "import-file"
        ],
        input_format: "pdf",
        layer: "above",
        image: [
          "import-logo"
        ],
        image_width: 500,
        position_vertical: "center",
        position_horizontal: "center",
        margin_vertical: 25,
        margin_horizontal: 25,
        opacity: 75,
      },
      {
        name: "export-watermarked-file",
        operation: "export/url",
        input: [
          "add-watermark"
        ]
      }
  ]
})
job = cloudconvert.Job.create(payload={
     "tasks": {
       "import-file": {
         "operation": "import/url",
         "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
       },
       "import-logo": {
         "operation": "import/url",
         "url": "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/logo.png"
       },
       "add-watermark": {
         "operation": "watermark",
         "input": [
           "import-file"
         ],
         "input_format": "pdf",
         "layer": "above",
         "image": [
           "import-logo"
         ],
         "image_width": 500,
         "position_vertical": "bottom",
         "position_horizontal": "right",
         "margin_vertical": 25,
         "margin_horizontal": 25,
         "opacity": 75
       },
       "export-watermarked-file": {
         "operation": "export/url",
         "input": [
           "add-watermark"
         ]
       }
     }
 })
final JobResponse createJobResponse = cloudConvertClient.jobs().create(
    ImmutableMap.of(
        "import-file",
            new UrlImportRequest()
                .setUrl("https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"),
        "import-logo",
            new UrlImportRequest()
                .setUrl("https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/logo.png"),
        "add-watermark",
            new AddWatermarkTaskRequest()
                .setInput("import-file")
                .setInputFormat("pdf"),
                .set("layer", "above"),
                .set("image", "import-logo")
                .set("image_width", 500)
                .set("position_vertical", "center")
                .set("position_horizontal", "center")
                .set("margin_vertical", 25)
                .set("margin_horizontal", 25)
                .set("opacity", 50)
        "export-watermarked-file",
            new UrlExportRequest()
                .setInput("add-watermark")
    )
).getBody();
var job = await CloudConvert.CreateJobAsync(new JobCreateRequest
      {
        Tasks = new
        {
          import-file = new ImportUrlCreateRequest
          {
            Url = "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/zombies.pdf"
          },
          import-logo = new ImportUrlCreateRequest
          {
            Url = "https://cloudconvert-blog.s3.eu-central-1.amazonaws.com/public/test-files/logo.png"
          },
          add-watermark = new WatermarkCreateRequest
          {
            Input = "import-file",
            Input_Format = "pdf",
            Options = new Dictionary<string, object> {
                          { "layer": "above" },
                          { "image_width": 500 },
                          { "image": "import-logo" },
                          { "position_vertical": "bottom" },
                          { "position_horizontal": "right" },
                          { "margin_vertical": 25 },
                          { "margin_horizontal": 25 },
                          { "opacity": 50 },
                        }
          },
          export-watermarked-file = new ExportUrlCreateRequest
          {
            Input = "add-watermark"
          }
        }
      });

Use our Job Builder to generate ready-to-use requests and code snippet for the CloudConvert API.

Job Builder API Documentation
On-demand, transparent pricing

Starting at 0.00 per file

When Converting Files

Corresponds to a one-timemonthly payment of . Checkout the full pricing information.