Watermark Removal API Integration: Four Upload Patterns and One Polling Loop (2026)

Last updated: October 2026

Search for watermark removal api integration and every result is a reference page: Tencent's action table, Dewatermark's endpoint list, WaveSpeed's model card, BytePlus's operator sheet. Each tells you what a single request looks like. None tells you what an integration looks like — how to move a two-hundred-megabyte file without a timeout, how to retry after a dropped response without paying twice, how long to wait before you poll again, or what a crashed job does to your bill. Those decisions are yours, and this guide works through them with five provider documents open.

My day job is building UnMark, a watermark removal product, so the wiring these APIs demand is the wiring we maintain at production scale. Yesterday's build-vs-buy guide settled the purchasing question with real price tables; this piece assumes you chose to integrate and walks the implementation: four upload patterns, one polling loop, the idempotency header that keeps retries safe, and the failure-billing rules that decide what a dead job costs.

The short version: every provider runs a shared asynchronous lifecycle — submit, poll, download — but the submit step splits into four distinct upload patterns, terminal-state sets range from three states to five, download links expire in as little as five minutes, task ids stop resolving after three days, and exactly one video provider refunds credits when a job fails. Each of those numbers changes the code you ship.

What Does a Watermark Removal API Integration Actually Look Like?

Every integration follows one asynchronous lifecycle: authenticate with a key, submit a job, poll a status endpoint until a terminal state arrives, then download the result through a time-limited link. The engineering work lives at the edges — getting large files to the endpoint safely, retrying without double-billing, and exiting the poll loop on every terminal state, not just success.

BytePlus describes the contract its Video Inpaint-Pro operator shares with the whole category: "The API of this operator is an asynchronous task interface. You need to submit a task via the Submit interface to obtain the task's task_id, then use the Poll interface to check the status of the corresponding task (task_id) and retrieve the operator's processing result." — BytePlus. Submit hands back a ticket, not a video. Everything a client does afterwards is ticket management: asking whether the ticket has finished, then collecting the output before the provider throws it away.

The reconstruction happening behind that ticket is video inpainting, and its quality ceiling holds whether you call it through an SDK or a curl command — our inpainting comparison covers why reconstruction beats cropping and blurring on real footage. What an integration adds on top is transport, timing, and money: the next four sections take each in turn.

Which Upload Pattern Does Each Provider Expect?

Four upload patterns cover the field: Dewatermark.ai hands you a signed URL and expects a raw PUT, Tencent references media already stored in its VOD library by FileId, WaveSpeed takes the job parameters directly inside the submit call, and Dewatermark.com accepts the image itself as a base64 payload guarded by an idempotency header. The pattern dictates your uploader code.

Dewatermark's video endpoint documents the signed-URL flow in four steps: "The process involves four steps: generating an upload URL, uploading the video file, submitting the task, and polling for completion" — Dewatermark API Reference. Step one, a POST to the upload endpoint, returns a task_id plus a Google Cloud Storage signed URL. Step two is an HTTP PUT of the raw file — the docs say PUT, not POST — with the body sent as application/octet-stream. Step three submits the task_id, optionally with a mask_brush PNG sized to match the video. The sequencing rule is printed in its own sentence: "Only proceed to Step 3 after the upload is complete. Do not submit the task before the video file has been fully uploaded." — Dewatermark API Reference. Submitting early strands a job pointing at half a file.

Tencent's RemoveWatermark action skips the transfer entirely: the input must already exist as a FileId inside Tencent's Video on Demand storage, so your pipeline ingests media into VOD first and passes the reference — the action returns a TaskId and the task pipeline does the rest. WaveSpeed's remover takes the opposite shape: one POST with the job parameters returns a prediction id, no separate upload leg at all. Dewatermark.com sends the image inline as a data URL alongside a black-and-white mask — "White pixels are repaired" — Dewatermark — and requires an ownershipAccepted flag in the payload itself, folding the permission question into the API contract the way our legality guide argues every removal workflow should.

Mask precision travels with two of the four patterns. Dewatermark.ai's mask_brush and Dewatermark.com's white-pixel mask both let you mark exactly which region to rebuild, and the narrower that region, the cheaper and cleaner the job — the arithmetic is in our mask-size economics piece. Tencent and WaveSpeed instead locate marks with their own detectors, which trades control for convenience.

Why Does Idempotency Decide Whether Your Retries Are Safe?

Networks drop responses at the worst moment — after the provider received your job but before you saw the confirmation. Idempotency is the property that makes resending safe: RFC 9110 defines a method as idempotent when many identical requests have the same intended effect as one. Retrying a non-idempotent submission without a key can create duplicate jobs and duplicate charges.

The specification lists the safe methods explicitly: "Of the request methods defined by this specification, PUT, DELETE, and safe request methods are idempotent." — RFC 9110. Notice what is missing from that list: POST, the method every submit endpoint uses. Each POST creates a new job by default, which is why one vendor builds the fix into its interface and most do not.

Dewatermark.com makes the idempotency key a required header: "Send an image, a matching black/white mask, and a unique Idempotency-Key. White pixels are repaired. HTTP 202 returns a job_id; poll GET /api/repairs/{job_id} for completion." — Dewatermark. And the retry rule is spelled out: "Retry an uncertain submission with the same key and identical input." — Dewatermark. Same key, same body, no matter how many times the network hiccups — the server recognises the duplicate and hands back the original job. Generate the key once per logical submission, store it beside the job record, and reuse it on every retry; a fresh key per attempt is just an expensive way of doing it wrong.

Tencent defends that failure mode from the other direction — server-side deduplication. Submissions carry a SessionId, and repeats bounce: "If there has been a request with the same identifier within the past seven days, an error will be returned for the current request." — Tencent Cloud. That guard punishes naive retry loops that regenerate identifiers, so read whichever provider you pick for its duplicate-submission behaviour before your first outage, not during it.

How Should You Poll Without Burning Through Your Rate Limits?

Polling is where integrations leak money and requests: every status check counts against the same per-key limits as real submissions. Start at the provider's suggested cadence — two seconds at WaveSpeed, two and a half at Dewatermark.com — stretch the interval as jobs run long, and stop on any terminal state, of which WaveSpeed documents five, not two.

WaveSpeed's polling guidance covers the whole loop in one sentence: "Start polling the result endpoint around every 2 seconds, increase the interval for long-running tasks, and stop on any terminal status." — WaveSpeed. Its documented terminal set is completed, failed, cancelled, timeout, and deleted — five exits, so a poller that only watches for completed will spin forever against a timed-out job, compounding the very rate-limit damage this section is about. Backoff is the practice of stretching that interval as the job ages: two seconds, then four, then eight caps your check volume on hour-long renders without delaying completion notice by more than a few seconds.

Dewatermark.com sets the interval at 2.5 seconds in its own JavaScript and Python examples, and removes the biggest polling fear outright: "Status polling does not consume the submission allowance." — Dewatermark. That single sentence means a tight poll loop cannot eat your 20-per-minute submission budget — though it can still eat your patience, which is what backoff is for. The terminal set here is three states: complete, failed, cancelled.

Set your timeout budget from processing-time reality, not hope. BytePlus publishes its operator's pace: lite mode processes 720p and 1080p in roughly three times the video's duration and 4K in roughly six times, while pro mode takes six times for 720p, ten for 1080p, and fifteen for 4K — a nine-minute 4K submission is a two-plus-hour wait. Build the poller's patience around those published multiples, and fan submissions out carefully — our batch-cleaning walkthrough shows what that looks like at twenty files.

What Does a Failed Job Actually Cost You?

Failure billing splits the field three ways. Dewatermark.ai refunds video credits outright when a job dies; Vidu's subscription credits behave the opposite way — failed renders still consume them, with no refunds; and WaveSpeed bills per output run, so a cancelled run's cost depends on when you cancelled it. Your retry policy should assume money moves on every attempt.

Dewatermark's refund rule shares a sentence with its metering rule: "The credit cost is 0.2 credits per second, which equals 1 credit for a 5-second video" — Dewatermark API Reference — and then: "Any failed or timeout tasks will result in a credit refund" — Dewatermark API Reference. That pairing changes retry math completely: resubmitting a failed job is free in credit terms, so aggressive retries cost you time and rate-limit headroom, not budget.

The contrast is generation platforms, where the meter runs on attempt rather than outcome. I documented the strict version in our Vidu guide: failed renders still consume credits, and the terms issue no refunds — a policy that turns a vendor-side outage into a line item on your bill. WaveSpeed sits between: "Pricing is per-output. The final charge scales with the parameters you set" — WaveSpeedAI — so a run that fails at the halfway mark bills per its own accounting, and per-output pricing also multiplies with batch size, the same effect we costed in the build-vs-buy guide.

Dewatermark.com's image credits add a size dimension instead: "Balanced cleanup costs ceil(processed megapixels) credits" — Dewatermark — and the higher-fidelity repair tier doubles that rate. A 4-megapixel Balanced repair is 4 credits, so a doubled-tier repair of the same image charges 8. Downloading never costs extra. Between plans — Starter at $7.99 for 100 monthly credits, Pro at $14.99 for 400, or a one-time 100-credit pack at $9 with no expiry — the per-megapixel rate lands between roughly 4 and 9 cents, which is the number to multiply by your failure rate, because at least one vendor in this comparison will not give the credits back.

Which Limits and Lifetimes Must Your Code Respect?

Three lifetimes bite production systems: rate limits per key, download-link expiry, and task-id retention. Dewatermark.com caps each key at 20 requests per minute and 500 per day, expires signed download links after five minutes, and keeps completed files for seven days. BytePlus task-ids stay retrievable for three days — after that, the result is gone no matter what your code expects.

Dewatermark.com states the storage rule and the fix in one line: "Completed files remain private for seven days; signed download links last five minutes and can be refreshed by reading the job again." — Dewatermark. Five minutes is shorter than most queue workers' garbage collection, so the durable pattern is to fetch the result the moment the poll loop exits and store the bytes yourself — treat provider storage as a mailbox, not an archive. If a scheduled consumer reads the link later, re-read the job to mint a fresh link rather than persisting the URL.

BytePlus draws the retention line on the ticket itself: "the task_id is valid for 3 days. After 3 days, you will not be able to retrieve the operator's processing result using this task_id." — BytePlus. Tencent's TaskId behaves the same way, and both providers' 600-RPM, concurrency-10 ceilings are generous for a single pipeline and tight for a fan-out service. Dewatermark.com's 20-per-minute and 500-per-day per-key defaults, by contrast, are sized for a small team from day one — plan key rotation before you hit them.

Key hygiene closes the list. Dewatermark.com stores only a hash of each key — "hash-only API keys you can rotate at any time" — Dewatermark — so a leaked key cannot even be read back from the dashboard, only rotated. And the placement rule is printed above every code sample: "Use API keys only from your backend." — Dewatermark. A key shipped inside a browser bundle is a public key with your credit balance attached.

Should You Integrate an API or Route Users to a Hosted Tool?

An API earns its keep when removal is one step inside a larger pipeline your team already operates — batch ingestion, review queues, automated publishing. If your users just need a clean file and a progress bar, a hosted tool delivers comparable inpainting without an uploader, a poller, or a terminal-state machine to maintain. Match the tool to the team.

The permission layer comes first, whichever way you go. Dewatermark.com hard-codes it as a request field — ownershipAccepted must be true — and frames the whole service as "permitted image cleanup" — Dewatermark. That is the same line we hold throughout this series: removal is for assets you own or are licensed to clean, and the legal scaffolding — copyright claims and, where a mark qualifies as copyright management information, Section 1202 — is in our legality guide. An API key automates the act; it does not authorize it.

For owned assets at pipeline scale, the four patterns above are the whole difference between a weekend and a quarter: pick the signed-URL flow for large video files, put an idempotency key on every submission, budget polling from published processing times, and persist results the moment links appear. Everyone else — creators cleaning Kling exports, Zoom recordings, or UGC handoffs — is who hosted products are for, and it is why we built UnMark: the uploader, poller, and retry logic already run on our side. You bring the file and the rights to clean it; the terminal states are our problem.

FAQ

What is an idempotency key in a watermark removal API?

It is a unique string your client generates once per logical submission and sends as a header, so the provider can recognise a retried request as the same job instead of a new one. Dewatermark.com requires an Idempotency-Key header on every create-job call and instructs developers to retry an uncertain submission with the same key and identical input. RFC 9110 supplies the underlying principle: only the request's intended effect should repeat, never the charge.

How long does an API take to clean a 10-minute video?

Plan in multiples of the video's duration, not minutes. BytePlus publishes that its lite mode takes roughly three times the video length at 720p and 1080p, and about six times at 4K, while pro mode runs six to fifteen times depending on resolution — a 10-minute 4K pro job is around two and a half hours. Budget your polling backoff and timeout thresholds from those published multiples before your first production run.

Can I call a watermark removal API directly from my frontend?

No — provider documentation is explicit that keys belong server-side. Dewatermark.com states it above every code sample: use API keys only from your backend, with browser clients going through the web app's own auth flow instead. A key bundled into frontend JavaScript is readable by anyone who opens devtools, and rate limits plus credit balances attach to it. Proxy removal requests through your own backend and hand the frontend only a job id.

Last updated: October 2026

References

BytePlus — Video Inpaint-Pro operator documentation (Official) (accessed October 2026)

Dewatermark.ai — API Reference (Official) (accessed October 2026)

Dewatermark.com — Developer API (Official) (accessed October 2026)

WaveSpeedAI — Video Watermark Remover API (Official) (accessed October 2026)

Tencent Cloud — RemoveWatermark API Reference (Official) (accessed October 2026)

RFC Editor — RFC 9110: HTTP Semantics, Section 9.2.2 (Official) (accessed October 2026)