apyhub
▣ FILE CONVERSION · FILE MANIPULATION

Generate Watermark For Videos Job API

Hosted on ApyHub

What it does

Video Watermark Generator adds a text or image watermark to a video and returns an asynchronous job you can poll for the finished file. Submit either a video URL or a multipart video file, choose the watermark type, and retrieve a presigned or CDN URL when processing completes.

Use watermark_text for a text overlay, or watermark_image for an image overlay. You can control placement with watermark_position, adjust transparency with watermark_opacity, and tune the look with watermark_font_size, watermark_font_color, watermark_text_padding, and watermark_text_background_color. For image watermarks, you can also set watermark_image_size; gif_loop is available when the watermark is a GIF. The URL-based endpoint also accepts size for output scaling and a persistent query flag.

The job response returns a job_id right away. Poll GET /jobs/:job_id to check whether the job is pending, successful, or failed. When it succeeds, the response includes the output url for the watermarked video. That makes it a fit for batch processing, content protection, branding, or adding review marks to generated clips without handling video encoding in your own service.

▣ ENDPOINT 01 / 03
POST
Submit generate video watermark job (source URL)
http://localhost:8080/apyhub/generate-video-watermark/url-to-json
QUICKSTARTGUIDE

Quickstart

Submit a video URL and a watermark to start an async video watermark job.

curl -X POST "http://localhost:8080/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 submitted 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 video watermarking job using a source video URL and watermark settings. The request accepts the source URL plus optional text or image watermark parameters, and the response returns a job identifier for later polling.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoNo description provided in the schema.

Request Body

ParameterTypeMandatoryDescription
video_urlStringYesHTTP(S) URL of the source video. Format: URI.
sizeStringNoOptional output video scale WIDTHxHEIGHT (even integers). Example: 1280x720.
gif_loopBooleanNoLoop GIF watermark for full video duration. Default: false.
watermark_textStringNoText overlay (alternative to image watermark).
watermark_imageStringNoImage overlay URL (.jpg, .jpeg, .png, .gif). Format: URI.
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_image_urlStringNoLegacy video-clips alias for watermark_image. Format: URI.
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 required job_id string field — the job identifier used for status polling. Success responses are returned immediately after async submission and are not wrapped in data.

ParameterTypeMandatoryDescription
job_idStringYesJob identifier for status polling. Format: UUID.

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
Provide **`watermark_text`** or an image watermark via **`watermark_image`** (legacy **`watermark_image_url`** also accepted).
▣ ENDPOINT 02 / 03
POST
Submit generate video watermark job (multipart file)
http://localhost:8080/apyhub/generate-video-watermark/file-to-json
QUICKSTARTGUIDE

Quickstart

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

curl -X POST "http://localhost:8080/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 required job_id string field — the UUID of the submitted 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.
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 multipart video file job to generate a video watermark. The request sends the source video and optional watermark settings, and the response returns a job identifier for later status polling.

Query Parameter(s)

AttributeTypeMandatoryDescription
persistentBooleanNoWhether the job should be persistent.

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 formatted as a UUID. This is the job identifier to use when polling for status after submission.

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 for polling.

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 03 / 03
GET
Check generate video watermark job status
http://localhost:8080/apyhub/generate-video-watermark/jobs/:job_id
QUICKSTARTGUIDE

Quickstart

Fetch the status of a watermarking job by its job_id.

curl -X GET "http://localhost:8080/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 can include job_id (string UUID), status (pending, successful, or failed), message (string), and url (string URI, 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 · 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.

About this endpoint

What it does

Checks the status of a generate video watermark job by job ID. When the job is successful, 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. The data object contains job_id as a UUID string, status as a string enum, and may include url and message depending on the job state.

ParameterTypeMandatoryDescription
dataObjectNoResponse payload object.
data.urlStringNoPresigned or CDN URL to the watermarked video output. Present when status is successful.
data.job_idStringNoJob identifier in UUID format.
data.statusENUMNoJob state. 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.

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
CatalogPricingBecome a providerStatus (opens in new tab)
Company
AboutBlogCareers (opens in new tab)Contact
Legal
Terms of ServicePrivacy PolicyProvider terms
© 2026 APYHUB · BUILT FOR DEVELOPERS