▣ FILE MANIPULATION · IMAGE PROCESSING

Apply Watermark on Images API

Hosted on ApyHub

What it does

Apply Watermark adds text or image watermarks to an input image and returns the processed file or a signed download link. Send the source image as Base64, multipart upload, or a URL, then choose whether the watermark comes from watermark_text, watermark_base64, watermark_image, or watermark_image_url.

You can control placement and appearance with fields like watermark_position, watermark_angle, watermark_opacity, watermark_font_size, watermark_font_color, watermark_image_size, and the text spacing and background options. The service also supports preserve_format and an output name for the generated file.

Use Apply Watermark when you need to brand marketing assets, label preview images, protect sample photos, or stamp internal documents before sharing them. The URL-based endpoints let you process remote images directly, while the Base64 and multipart endpoints fit backend workflows that already handle file uploads or encoded content.

Choose the download endpoints when you want the transformed image returned as binary data. Choose the link endpoints when your app prefers a signed URL in the response data field.

▣ ENDPOINT 01 / 06

POST

Apply watermark (base64 bodies, download)

http://localhost:8080/apyhub/apply-watermark/base64/download

QUICKSTARTGUIDE

Quickstart

Create a watermarked image from a Base64-encoded source image and return the processed file.

curl -X POST "http://localhost:8080/apyhub/apply-watermark/base64/download" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
    "watermark_text": "Confidential"
  }'

What you'll get back

Returns a binary file containing the generated image.

TRY ITLIVE · 60 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Applies a watermark to a source image provided as Base64 and returns the processed file as binary content. The request body carries the source image and optional watermark configuration, while the response is the generated file itself.

Query Parameter(s)

Attribute	Type	Mandatory	Description
output	String	No	Output filename stem.
preserve_format	Boolean	No	Whether to preserve the input file format.

Request Body

Parameter	Type	Mandatory	Description
size	String	No	Image size setting.
image_base64	String	Yes	Source image as standard Base64-encoded image bytes.
watermark_text	String	No	Watermark text to apply.
watermark_angle	String	No	Watermark rotation angle.
watermark_base64	String	No	Watermark image as Base64. Use this or `watermark_text` depending on the desired watermark type.
watermark_opacity	String	No	Watermark opacity setting.
watermark_position	String	No	Watermark placement.
watermark_font_size	String	No	Watermark text font size.
watermark_font_color	String Array	No	Watermark text font color components.
watermark_image_size	String	No	Watermark image size setting.
watermark_text_padding	String	No	Watermark text padding.
watermark_text_alignment	String	No	Watermark text alignment.
watermark_text_line_spacing	String	No	Watermark text line spacing.
watermark_text_background_color	String	No	Watermark text background color.

Response

Returns a binary file in the response body. The output schema is a single binary string, so there is no JSON wrapper or named JSON fields to parse.

Parameter	Type	Mandatory	Description
binary body	String	Yes	Binary response content containing the watermarked file.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

Body

Name

Type

Description

bodyREQUIRED

object

Source image as Base64 (`image_base64` required). Watermark via `watermark_text` or `watermark_base64`; placement/style keys match URL JSON / multipart parity.

▣ ENDPOINT 02 / 06

POST

Apply watermark (base64 bodies, signed URL)

http://localhost:8080/apyhub/apply-watermark/base64/link

QUICKSTARTGUIDE

Quickstart

Upload a Base64 image and a watermark, then return a watermarked image URL.

curl -X POST "http://localhost:8080/apyhub/apply-watermark/base64/link" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "watermark_text": "Confidential"
  }'

What you'll get back

Returns a JSON object with a data string field containing a URI for the watermarked image.

{
  "data": "https://example.com/watermarked-image.png"
}

TRY ITLIVE · 60 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Applies a watermark to a source image provided as Base64 and returns a JSON object containing a data URI string for the resulting output.

Query Parameter(s)

Attribute	Type	Mandatory	Description
output	String	No	Output name.
preserve_format	Boolean	No	Preserves the source image format when set.

Request Body

Parameter	Type	Mandatory	Description
size	String	No	Output size.
image_base64	String	Yes	Required — standard Base64-encoded image bytes. Source image to watermark.
watermark_text	String	No	Watermark text. Use this or `watermark_base64` for the watermark source.
watermark_angle	String	No	Watermark rotation angle.
watermark_base64	String	No	Base64-encoded watermark image. Use this or `watermark_text` for the watermark source.
watermark_opacity	String	No	Watermark opacity.
watermark_position	String	No	Watermark placement.
watermark_font_size	String	No	Watermark text font size.
watermark_font_color	String Array	No	Watermark text font color components.
watermark_image_size	String	No	Watermark image size.
watermark_text_padding	String	No	Watermark text padding.
watermark_text_alignment	String	No	Watermark text alignment.
watermark_text_line_spacing	String	No	Watermark text line spacing.
watermark_text_background_color	String	No	Watermark text background color.

Response

Returns a JSON object with a data string field formatted as a URI. The success response body contains the generated result location or data reference in data.

Parameter	Type	Mandatory	Description
data	String	Yes	URI to the generated output.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

Body

Name

Type

Description

bodyREQUIRED

object

Source image as Base64 (`image_base64` required). Watermark via `watermark_text` or `watermark_base64`; placement/style keys match URL JSON / multipart parity.

▣ ENDPOINT 03 / 06

POST

Apply watermark (multipart, download)

http://localhost:8080/apyhub/apply-watermark/multi-part/download

QUICKSTARTGUIDE

Quickstart

Upload an image and a watermark as multipart form data to generate a watermarked file.

curl -X POST "http://localhost:8080/apyhub/apply-watermark/multi-part/download" \
  -H "apy-token: $APY_TOKEN" \
  -F "image=@/path/to/image.jpg"

What you'll get back

Returns a binary file (string with format: binary) — the downloaded watermarked image output.

(binary file content)

TRY ITLIVE · 60 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Applies a watermark to an uploaded image and returns the processed file as binary data. The request sends the source image plus optional watermark settings in the multipart body.

Query Parameter(s)

Attribute	Type	Mandatory	Description
output	String	No	Output file name or identifier.
preserve_format	Boolean	No	Whether to preserve the original file format.

Request Body

Parameter	Type	Mandatory	Description
image	String	Yes	The source image file to watermark. Binary upload.
size	String	No	Size setting for the operation.
watermark_text	String	No	Watermark text to apply.
watermark_angle	String	No	Watermark angle setting.
watermark_image	String	No	Watermark image file to apply. Binary upload.
watermark_opacity	String	No	Watermark opacity setting.
watermark_position	String	No	Watermark position setting.
watermark_font_size	String	No	Watermark text font size.
watermark_font_color	String	No	Watermark text font color.
watermark_image_size	String	No	Watermark image size setting.
watermark_text_padding	String	No	Watermark text padding setting.
watermark_text_alignment	String	No	Watermark text alignment setting.
watermark_text_line_spacing	String	No	Watermark text line spacing setting.
watermark_text_background_color	String	No	Watermark text background color.

Response

Returns binary file data as the success response. The output is a single binary payload, not a JSON object.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

Body

Name

Type

Description

bodyREQUIRED

object

—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 04 / 06

POST

Apply watermark (multipart, signed URL)

http://localhost:8080/apyhub/apply-watermark/multi-part/link

QUICKSTARTGUIDE

Quickstart

Upload an image and apply a watermark from a public image URL in one request.

curl -X POST "http://localhost:8080/apyhub/apply-watermark/multi-part/link" \
  -H "apy-token: $APY_TOKEN" \
  -F "image=@/path/to/image.jpg"

What you'll get back

Returns a JSON object with a data string field containing a URI for the generated file.

{
  "data": "https://example.com/output.jpg"
}

TRY ITLIVE · 60 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

About this endpoint

What it does

Applies a watermark to the provided image and returns a JSON object containing a data URI string for the resulting file. The request is sent as multipart data, with the source image required and optional watermark settings supplied in the body.

Query Parameter(s)

Attribute	Type	Mandatory	Description
output	String	No	Output filename/identifier for the generated result.
preserve_format	Boolean	No	Whether to preserve the input file format.

Request Body

Parameter	Type	Mandatory	Description
image	String	Yes	Source image file to watermark.
size	String	No	Size setting for the watermark operation.
watermark_text	String	No	Text to use as the watermark.
watermark_angle	String	No	Watermark angle.
watermark_image	String	No	Watermark image file.
watermark_opacity	String	No	Watermark opacity.
watermark_position	String	No	Watermark position.
watermark_font_size	String	No	Watermark font size.
watermark_font_color	String	No	Watermark font color.
watermark_image_size	String	No	Watermark image size.
watermark_text_padding	String	No	Watermark text padding.
watermark_text_alignment	String	No	Watermark text alignment.
watermark_text_line_spacing	String	No	Watermark text line spacing.
watermark_text_background_color	String	No	Watermark text background color.

Response

Returns a JSON object with a data string field formatted as a URI. This field contains the result produced by the watermark operation.

Parameter	Type	Mandatory	Description
data	String	Yes	Result URI returned by the endpoint.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

Body

Name

Type

Description

bodyREQUIRED

object

—

Max 100MB total per request (all files combined). Larger? Use this API's URL-based endpoint instead, if it has one.

▣ ENDPOINT 05 / 06

POST

Apply watermark (URL fetch, download)

http://localhost:8080/apyhub/apply-watermark/url/download

QUICKSTARTGUIDE

Quickstart

Generate a watermarked image from an image URL using a text watermark.

curl -X POST "http://localhost:8080/apyhub/apply-watermark/url/download?output=my-invite" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://assets.apyhub.com/samples/sample.jpg",
    "watermark_text": "Confidential"
  }'

What you'll get back

Returns the generated file as raw binary data.

TRY ITLIVE · 60 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Applies a watermark to an image fetched from a URL and returns the processed file as binary output. The request body supplies the source image URL plus either watermark text or a watermark image URL, along with optional styling and placement settings.

Query Parameter(s)

Attribute	Type	Mandatory	Description
output	String	No	Output filename or identifier sent as a query parameter.
preserve_format	Boolean	No	Whether to preserve the original format.

Request Body

Parameter	Type	Mandatory	Description
size	String	No	Size setting for the watermark operation.
image_url	String	No	Source image URL to fetch and watermark. Must be a URI.
watermark_text	String	No	Watermark text to apply.
watermark_angle	String	No	Watermark angle setting.
watermark_opacity	String	No	Watermark opacity setting.
watermark_position	String	No	Watermark position setting.
watermark_font_size	String	No	Watermark font size setting.
watermark_image_url	String	No	Watermark image URL to apply instead of text. Must be a URI.
watermark_font_color	String Array	No	Watermark font color values.
watermark_image_size	String	No	Watermark image size setting.
watermark_text_padding	String	No	Watermark text padding setting.
watermark_text_alignment	String	No	Watermark text alignment setting.
watermark_text_line_spacing	String	No	Watermark text line spacing setting.
watermark_text_background_color	String	No	Watermark text background color setting.

Response

Returns a binary file response (string with binary format) containing the watermarked output image.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

Body

Name

Type

Description

bodyREQUIRED

object

Watermark URL mode. Image from `image_url`. Either `watermark_text` or watermark image URL (`watermark_image_url`). Style/placement fields mirror multipart names (`watermark_position`, `watermark_opacity`, …).

▣ ENDPOINT 06 / 06

POST

Apply watermark (URL fetch, signed URL)

http://localhost:8080/apyhub/apply-watermark/url/link

QUICKSTARTGUIDE

Quickstart

Create a watermarked image from an image URL and return the output URL.

curl -X POST "http://localhost:8080/apyhub/apply-watermark/url/link" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://assets.apyhub.com/samples/sample.jpg",
    "watermark_text": "Confidential"
  }'

What you'll get back

Returns a JSON object with a data string field containing the output image URL.

{
  "data": "https://example.com/watermarked-image.jpg"
}

TRY ITLIVE · 60 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Applies a watermark to an image fetched from a signed URL. The request body provides the source image URL and either watermark text or a watermark image URL, plus optional styling and placement settings; the response returns the processed file as a URI string in a JSON object.

Query Parameter(s)

Attribute	Type	Mandatory	Description
output	String	No	Output name.
preserve_format	Boolean	No	Preserves the original format when set.

Request Body

Parameter	Type	Mandatory	Description
size	String	No	Output size.
image_url	String	No	Source image URL to watermark. Must be a URI.
watermark_text	String	No	Watermark text to apply.
watermark_angle	String	No	Watermark angle.
watermark_opacity	String	No	Watermark opacity.
watermark_position	String	No	Watermark position.
watermark_font_size	String	No	Watermark font size.
watermark_image_url	String	No	Watermark image URL. Must be a URI.
watermark_font_color	String Array	No	Watermark font color values.
watermark_image_size	String	No	Watermark image size.
watermark_text_padding	String	No	Watermark text padding.
watermark_text_alignment	String	No	Watermark text alignment.
watermark_text_line_spacing	String	No	Watermark text line spacing.
watermark_text_background_color	String	No	Watermark text background color.

Response

Returns a JSON object with a data URI string field containing the processed image location.

Parameter	Type	Mandatory	Description
data	String	Yes	URI of the generated output.

Query parameters

Name

Type

Description

outputOPTIONAL

string

—

preserve_formatOPTIONAL

boolean

—

Body

Name

Type

Description

bodyREQUIRED

object

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.