Watermark API

#What the Watermark API does

The Watermark API provides 21 endpoints for adding, managing, detecting, and removing watermarks across 7 file types: images, PDFs, videos, audio, documents, 3D models, and eBooks.

#Endpoints at a glance

#Supported file formats

#Quick start

Add a text watermark to an image in one API call:

curl -X POST https://api.yeb.to/v1/watermark/add-text \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_KEY",
    "file_url": "https://example.com/photo.jpg",
    "text": "© 2026 My Company",
    "opacity": 0.5,
    "position": "bottom-right",
    "font_size": 36,
    "color": "#ffffff"
  }'

The response includes the watermarked file URL immediately for small files, or a job_id for async processing of larger files:

{
  "job_id": 1234,
  "status": "completed",
  "url": "https://storage.yeb.to/watermark/output/abc123.jpg",
  "file_size": 245678,
  "credits_used": 0.10,
  "response_code": 200
}

#Watermark types explained

Text watermark

The add-text endpoint overlays customizable text. Control the font family, size (8–500px), color, opacity (0–1), position (9 presets + custom x/y), rotation (-360° to 360°), and optional shadow or outline effects.

Image watermark

The add-image endpoint overlays a logo or image. Upload via watermark_image, watermark_image_url, or watermark_image_base64. Control opacity, position, scale, and rotation.

Pattern watermark

The add-pattern endpoint tiles repeating text across the entire file — commonly used for “DRAFT” or “CONFIDENTIAL” overlays. Adjust font size, color, opacity, rotation, and horizontal/vertical spacing.

Code watermark (QR/barcode)

The add-code endpoint embeds a machine-readable code. Supported formats: QR, Code128, Code39, EAN-13, EAN-8, and DataMatrix. Optionally encrypt the payload with an encryption_key for tamper-proof verification.

Audio watermark

The add-audio endpoint embeds audio marks into audio/video files. Four types: voice_tag (spoken watermark), tone (beep/chime), intro_outro (clip at start/end), and ultrasonic (inaudible high-frequency mark for tracking).

#Batch processing

Watermark up to 50 files in a single API call using the batch endpoint. All files receive the same watermark configuration. The request returns a batch_id that you can poll with batch-status to track progress.

• Each file is processed independently and asynchronously
• Credits are charged per file (same rate as individual endpoints)
• Failed files don’t block the rest of the batch
• Results are available for download as each file completes

#Reusable templates

Save your watermark configuration as a template to reuse across requests. Templates store the watermark type, position, opacity, font settings, and all other parameters.

1. Save — template-save creates or updates a template with a name and config object
2. List — templates returns all your saved templates, optionally filtered by category
3. Use — pass a template_id to any watermark endpoint to apply saved settings
4. Delete — template-delete removes a template by ID

#Code watermarks & verification

Code watermarks enable machine-readable tracking. The workflow:

1. add-code — embed a QR/barcode with an optional encrypted payload
2. read-code — scan the code from an image to extract the raw payload
3. decode-code — decrypt the payload using your encryption key

This is useful for tracking document provenance, verifying authenticity, or embedding license keys in media files.

#Detection & removal

Three AI-powered endpoints for working with existing watermarks:

• detect (0.50 credits) — analyzes an image to find watermark regions, returning bounding boxes and confidence scores
• verify (0.30 credits) — checks if a specific tracking ID or steganographic mark is present in a file
• remove (1.00 credits) — attempts AI-powered watermark removal from images (works best on semi-transparent text overlays)

#Brand kits

Brand kits store your organization’s logos, fonts, colors, and default watermark configuration. Once saved, they can be referenced across all watermark endpoints for consistent branding.

• brand-kit-save — create or update a kit with name, logos, fonts, colors, and default config
• brand-kit-list — retrieve all your brand kits
• brand-kit-delete — remove a kit by ID

#Authentication

All requests require an api_key parameter in the JSON body. Get your key from the dashboard. The key identifies your account and is used for credit billing and rate limiting.

#Error handling

Standard HTTP status codes are used. Common errors: