apyhub
▣ FILE CONVERSION · FILE MANIPULATION

Generate Watermark For Videos Job API

What it does

Video Watermark Generator adds a text or image watermark to a source video and returns a job ID you can poll until the output is ready.

Send either a video file or a video URL, then choose a watermark_text or watermark_image. You can also set size to scale the output video, watermark_position to place the overlay, and watermark_opacity to control how visible it is. For text watermarks, you can tune watermark_font_size, watermark_font_color, watermark_text_padding, and watermark_text_background_color. For image watermarks, you can adjust watermark_image_size; gif_loop is available when the watermark is a GIF.

Use Video Watermark Generator when you need to brand social clips, stamp review exports, or protect preview videos before sharing them with clients or internal teams. The job runs asynchronously, so the submit endpoint returns a job_id immediately instead of blocking on video processing.

Check /jobs/:job_id to read back the job status. When the job is successful, the response includes a url for the watermarked video. If the job is still processing or has failed, you also get a human-readable message.

▣ ENDPOINT 01 / 03
POST
Submit generate video watermark job (multipart file)
https://api.eu.apyverse.com/apyhub/generate-video-watermark/file-to-json

QUICKSTART

GUIDE

Quickstart

Upload a video and an optional watermark to start an async watermarking job.

curl -X POST "https://api.eu.apyverse.com/apyhub/generate-video-watermark/file-to-json" \
  -H "apy-token: $APY_TOKEN" \
  -F "video=@/path/to/video.mp4" \
  -F "watermark_image=@/path/to/watermark.png"

What you'll get back

Returns a JSON object with a job_id string field — the UUID for polling the job status.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
TRY ITLIVE · 400 ATOMS
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.
body*
Optional output video scale `WIDTHxHEIGHT` (even integers).
Source video file.
Set to `true` or `1` to loop GIF watermark for full video duration.
Text overlay (alternative to `watermark_image`).
Image overlay file (`.jpg`, `.jpeg`, `.png`, `.gif`).
Opacity **0.0–1.0**. Default **0.5**.
Text watermark font size in pixels. Default **24**.
Hex color for text. Default **`#ffffff`**.
Image scale (`-1:N` or `WIDTHxHEIGHT`). Default **`-1:50`**.
Text padding in pixels. Default **10**.
Hex background box color; omit for no box.

About this endpoint

What it does

Submits a video watermarking job using a multipart file upload. The request includes the source video plus optional watermark and formatting settings, and the response returns a job identifier for polling the async job.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoControls whether the job should persist.

Request Body

ParameterTypeMandatoryDescription
videoStringYesSource video file.
sizeStringNoOptional output video scale WIDTHxHEIGHT (even integers).
gif_loopStringNoSet to true or 1 to loop GIF watermark for full video duration.
watermark_textStringNoText overlay (alternative to watermark_image).
watermark_imageStringNoImage overlay file (.jpg, .jpeg, .png, .gif).
watermark_opacityStringNoOpacity 0.0–1.0. Default 0.5.
watermark_positionENUMNoAllowed values: top_right, top_left, bottom_right, bottom_left, center, bottom_center, top_center, center_left, center_right. Default bottom_right.
watermark_font_sizeStringNoText watermark font size in pixels. Default 24.
watermark_font_colorStringNoHex color for text. Default #ffffff.
watermark_image_sizeStringNoImage scale (-1:N or WIDTHxHEIGHT). Default -1:50.
watermark_text_paddingStringNoText padding in pixels. Default 10.
watermark_text_background_colorStringNoHex background box color; omit for no box.

Response

Returns a JSON object with a job_id string field — a UUID job identifier to use for status polling.

Status CodeResponse TypeDescription
200ObjectSuccess response containing job_id.

Notes

This endpoint kicks off an async job and returns immediately with a job identifier; the actual work runs in the background. Pair this call with the corresponding job_check endpoint — poll that until the status reaches a terminal state to retrieve the result. Extract the job_id field from the response.

Query parameters

Name
Type
Description
persistentOPTIONAL
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 02 / 03
POST
Submit generate video watermark job (source URL)
https://api.eu.apyverse.com/apyhub/generate-video-watermark/url-to-json

QUICKSTART

GUIDE

Quickstart

Submit a video URL and a watermark to start an asynchronous video watermarking job.

curl -X POST "https://api.eu.apyverse.com/apyhub/generate-video-watermark/url-to-json" \
  -H "apy-token: $APY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://assets.apyhub.com/samples/sample.mp4",
    "watermark_text": "Sample watermark"
  }'

What you'll get back

Returns a JSON object with a job_id string field — the UUID of the created job for later status polling.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}
TRY ITLIVE · 400 ATOMS
Loading your default key…
The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.
body*
Provide **`watermark_text`** or an image watermark via **`watermark_image`** (legacy **`watermark_image_url`** also accepted).
Optional output video scale `WIDTHxHEIGHT` (even integers).
Loop GIF watermark for full video duration.
HTTP(S) URL of the source video.
Text overlay (alternative to image watermark).
Image overlay URL (`.jpg`, `.jpeg`, `.png`, `.gif`).
Opacity **0.0–1.0**. Default **0.5**.
Text watermark font size in pixels. Default **24**.
Legacy video-clips alias for `watermark_image`.
Hex color for text. Default **`#ffffff`**.
Image scale (`-1:N` or `WIDTHxHEIGHT`). Default **`-1:50`**.
Text padding in pixels. Default **10**.
Hex background box color; omit for no box.

About this endpoint

What it does

Submits an async job that generates a watermarked video from a source video URL. You provide the source video_url plus either watermark_text or an image watermark, and the endpoint returns a job identifier immediately.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoQuery flag with no schema description beyond being a boolean.

Request Body

ParameterTypeMandatoryDescription
video_urlStringYesHTTP(S) URL of the source video.
sizeStringNoOptional output video scale WIDTHxHEIGHT (even integers).
gif_loopBooleanNoLoop GIF watermark for full video duration. Default: false.
watermark_textStringNoText overlay, used as an alternative to image watermark.
watermark_imageStringNoImage overlay URL; accepted formats are .jpg, .jpeg, .png, .gif.
watermark_opacityStringNoOpacity value from 0.0 to 1.0. Default: 0.5.
watermark_positionENUMNoWatermark position. Allowed values: top_right, top_left, bottom_right, bottom_left, center, bottom_center, top_center, center_left, center_right. Default: bottom_right.
watermark_font_sizeStringNoText watermark font size in pixels. Default: 24.
watermark_image_urlStringNoLegacy alias for watermark_image.
watermark_font_colorStringNoHex color for text. Default: #ffffff.
watermark_image_sizeStringNoImage scale. Accepts -1:N or WIDTHxHEIGHT. Default: -1:50.
watermark_text_paddingStringNoText padding in pixels. Default: 10.
watermark_text_background_colorStringNoHex background box color; omit to disable the background box.

Response

Returns a JSON object with a required job_id string field. The job_id is a UUID that you use for status polling.

AttributeTypeMandatoryDescription
job_idStringYesJob identifier for status polling.

Notes

This endpoint kicks off an async job and returns immediately with a job identifier; the actual work runs in the background. Pair this call with the corresponding job_check endpoint — poll that until the status reaches a terminal state to retrieve the result. Extract the job_id field from the response to poll later.

Query parameters

Name
Type
Description
persistentOPTIONAL
boolean
—

Body

Name
Type
Description
bodyREQUIRED
object
Provide **`watermark_text`** or an image watermark via **`watermark_image`** (legacy **`watermark_image_url`** also accepted).
▣ ENDPOINT 03 / 03
GET
Check generate video watermark job status
https://api.eu.apyverse.com/apyhub/generate-video-watermark/jobs/:job_id

QUICKSTART

GUIDE

Quickstart

Check the status of a watermarked video job by its job ID.

curl -X GET "https://api.eu.apyverse.com/apyhub/generate-video-watermark/jobs/:job_id" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with a data object. The data object may include job_id, status, message, and url — url is present when the job is successful.

{
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "successful",
    "url": "https://assets.apyhub.com/samples/sample.mp4"
  }
}
TRY ITLIVE · 5 ATOMS
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

Checks the status of a previously submitted generate video watermark job by job_id and returns the job record inside a data object. When the job completes successfully, the response includes the output video URL.

Path Parameter(s)

AttributeTypeMandatoryDescription
job_idStringYesJob identifier in UUID format.

Response

Returns a JSON object with a data object field containing the job status details. The data object includes job_id (string UUID), status (string enum), optional message (string), and optional url (string URI) when the job is successful.

AttributeTypeMandatoryDescription
dataObjectNoJob status payload. Contains job_id, status, optional message, and optional url.
data.job_idStringNoJob identifier in UUID format.
data.statusENUMNoJob status. Allowed values: pending, successful, failed. pending while submitted or processing, successful when output is ready, failed when the worker marked the job failed.
data.messageStringNoHuman-readable status message for pending or failed responses.
data.urlStringNoPresigned or CDN URL to the watermarked video output. Present when status is successful.

Path parameters

Name
Type
Description
job_idREQUIRED
string
—
▣ 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.

Product
CatalogPricingQuickstartBecome a providerStatus (opens in new tab)
Company
AboutBlogCareers (opens in new tab)Contact
Legal
Terms of ServicePrivacy PolicyProvider terms
© 2026 APYHUB · BUILT FOR DEVELOPERS