Name: AddWatermark – Brand & Protect Videos | From $5/mo | API.market
Brand: magicapi
SKU: api-magicapi-video-watermarking-api
Availability: InStock
Author: API Market

Shashank Agarwal

# 💧 Fast Video Watermarking API (AddWatermark)

## Overview
This API enables you to automatically embed a watermark onto video files. Whether you’re a content creator or a business aiming to protect brand integrity, this fast, reliable watermarking solution quickly processes your video and returns a watermarked version for your use. 

Key functionality includes:
- Defining custom text watermarks.
- Adjusting text size (font size).
- Preserving video integrity while overlaying a high-quality watermark.

## Features
- Rapid Watermarking: Fast, server-side processing for quick results.
- Flexible Font Size: Specify the exact watermark size up to 500 for precise positioning and style.
- Simple and Reliable: Asynchronous request/response handling for efficient usage in both small and large-scale applications.
- Seamless Integration: Straightforward endpoints that integrate with any system or application.

## Use Cases
1. Video Content Branding: Marketing agencies adding client logos or brand text to ensure credit and deter unauthorized use.  
2. Educational Platforms: E-learning providers watermarking instructional videos to protect proprietary materials.  
3. Corporate Policy Videos: Companies marking training clips or announcements with distinct brand elements.  
4. Social Media Creators: Influencers and video bloggers embedding their handles or branding on videos before sharing.  
5. Journalist Footage Protection: News outlets and reporters ensuring exclusive coverage remains clearly attributed.

## Visual Examples

Below is an example of an input video and the final watermarked output. Both show how the watermark is applied with minimal intrusion on the original content.

### Sample Input Video
![Sample Input Video](https://replicate.delivery/pbxt/JzweHYSSY69C9uUq2wAcqX3suV9zdL3C6Ujk2hrxynOJ0JHm/vidswap600883.mp4)

### Sample Output Video
![Sample Output Video](https://replicate.delivery/pbxt/nll0sjfsxGwbNy6A5zfIur4nlZM6An58NYas6ufKgdWd3qeHB/tmpzf079ddnvidswap600883_watermarked.mp4)

The above example illustrates how the API adds “FULLJOURNEY.AI” (or your custom text) as a clear, visible watermark over the entire video.

## Pricing
- 1 API unit = 1 video processed.  
- GET requests to check prediction status are free and do not count toward API unit usage.  
- Multiple pricing tiers are available, accommodating anything from small-scale testing to enterprise-level usage.  

## API Documentation

### Base URL
All API requests should be made to:
```
https://prod.api.market/api/v1/magicapi/video-watermarking-api
```

### Authentication
Include your API key using the header:
```
x-magicapi-key: YOUR_API_MARKET_KEY
```
All requests require this authentication header.

### Asynchronous Processing
This API processes video watermarking asynchronously. When you launch a prediction, the response includes a unique prediction ID. You must then poll the prediction status until it’s completed.

1. Make a POST request to create a prediction and receive a prediction ID.  
2. Poll the GET endpoint with the prediction ID and check the status.  
3. Continue polling on regular intervals (e.g., 1 second).  
4. Once the status is "succeeded," the process is complete, and the output URL will be available.  

If the status becomes "failed," the process has ended in an error. Implement a maximum timeout of 10 minutes and handle failed or timed-out predictions within your code.

### Endpoints

#### 1. Create a Prediction
```
POST /api/v1/magicapi/video-watermarking-api/predictions
```
Create a new watermarking job.

• Request Body:
```json
{
  "version": "f274d1efdd9d249cef68fccd028d70e4134b2d59f2b02b42a4e78350849d0e57",
  "input": {
    "video": "<VIDEO_URL>",
    "size": 40,
    "watermark": "FULLJOURNEY.AI"
  }
}
```
- video (string, required): URL of the video to be watermarked.  
- size (integer, optional, default=40): Specifies the watermark’s font size.  
- watermark (string, optional, default="FULLJOURNEY.AI"): The watermark text.

• Example cURL:
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/video-watermarking-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "f274d1efdd9d249cef68fccd028d70e4134b2d59f2b02b42a4e78350849d0e57",
    "input": {
      "video": "https://example.com/your-video.mp4",
      "size": 40,
      "watermark": "YourBrand"
    }
  }'
```

• Example Response:
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "f274d1efdd9d249cef68fccd028d70e4134b2d59f2b02b42a4e78350849d0e57",
  "status": "starting",
  "created_at": "2025-04-24T18:10:55.086Z"
}
```

#### 2. Get Prediction Status & Result
```
GET /api/v1/magicapi/video-watermarking-api/predictions/{id}
```
Retrieve the status of your prediction, whether it’s still being processed, or if it has completed.

• Path Parameter:
- id (string): The unique prediction ID returned by the create prediction request.

• Example cURL:
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/video-watermarking-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"
```

• Example Response (if succeeded):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://example.com/output-watermarked-video.mp4",
  "created_at": "2023-01-01T12:00:00.000Z",
  "started_at": "2023-01-01T12:00:05.000Z",
  "completed_at": "2023-01-01T12:01:00.000Z"
}
```

## Status Codes
- 200 OK: Request successful. Status retrieval or other GET requests.  
- 201 Created: Prediction request accepted and processed successfully.  
- 400 Bad Request: Invalid input or malformed request.  
- 401 Unauthorized: Missing or invalid API key.  
- 403 Forbidden: The API key is valid but lacks enough permissions.  
- 404 Not Found: The requested resource (e.g., prediction ID) doesn’t exist.  
- 429 Too Many Requests: Rate limit exceeded. Throttle requests and retry later.  
- 500 Internal Server Error: A server issue occurred; try again later.  
- 503 Service Unavailable: The service is overloaded or under maintenance.  

## Rate Limits
Requests may be subject to a rate limit. If you receive a 429 Too Many Requests error, reduce your request frequency or wait before retrying. For higher throughput, consider upgrading your pricing plan.

## Error Handling
When encountering errors:
- Check the status code for guidance on how to respond.  
- Examine the JSON error response for specific details.  
- If it’s a transient error (e.g., 503 or network issue), implement a retry with exponential backoff.  
- For 400 or 401 errors, correct any invalid parameters or re-check your authentication:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'video' is required",
    "status": 400
  }
}
```

## Implementation Guide
Below are examples in JavaScript, Python, and cURL showing how to authenticate, create predictions, poll for status, and handle the asynchronous workflow.

### Example Code

```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/video-watermarking-api";

async function createAndWaitForPrediction(inputData) {
  try {
    // Step 1: Create the prediction
    const response = await fetch(`${baseUrl}/predictions`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-magicapi-key": apiKey
      },
      body: JSON.stringify({
        version: "f274d1efdd9d249cef68fccd028d70e4134b2d59f2b02b42a4e78350849d0e57",
        input: inputData
      })
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    // Check prediction status
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: {
        "x-magicapi-key": apiKey
      }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${response.statusText}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed") {
      throw new Error(`Prediction failed: ${prediction.error || "Unknown error"}`);
    }

    // Wait before next poll
    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}
```

```python
# Python example with proper polling and timeout
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/video-watermarking-api"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-magicapi-key": API_KEY
    }
    
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={
            "version": "f274d1efdd9d249cef68fccd028d70e4134b2d59f2b02b42a4e78350849d0e57",
            "input": input_data
        }
    )
    
    if response.status_code != 200 and response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")
    
    prediction = response.json()
    prediction_id = prediction["id"]
    
    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second

    headers = {"x-magicapi-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(
            f"{BASE_URL}/predictions/{prediction_id}",
            headers=headers
        )
        
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")
        
        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]
        
        if prediction["status"] == "failed":
            error_msg = prediction.get("error", "Unknown error")
            raise Exception(f"Prediction failed: {error_msg}")
        
        # Wait before next poll
        time.sleep(POLL_INTERVAL)

    raise Exception("Prediction timed out after 10 minutes")
```

```bash
# cURL example

# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/video-watermarking-api/predictions" \
  -H "Content-Type: application/json" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "f274d1efdd9d249cef68fccd028d70e4134b2d59f2b02b42a4e78350849d0e57",
    "input": {
      "video": "https://example.com/your-video.mp4",
      "size": 40,
      "watermark": "YourBrand"
    }
  }'

# Response will include a prediction ID, for example:
# {"id": "ufawqhfynnddngldkgtslldrkq", "status": "starting"}

# Step 2: Poll for prediction status
curl -X GET "https://prod.api.market/api/v1/magicapi/video-watermarking-api/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-magicapi-key: YOUR_API_MARKET_KEY"

# Repeat this GET request until "status" is "succeeded" or "failed"
```

### Performance Optimization
- Batch requests to reduce overhead if you have a large queue of video files.  
- Keep watermark text concise to minimize processing overhead.  
- Implement caching mechanisms for commonly repeated requests if applicable.  
- Use a stable interval of 1 second when polling, and avoid frequent queries (under 1 sec) to prevent rate limiting.

## FAQ

1. **Does the API support non-video files?**  
   Currently, this API is optimized for video watermarking only.  

2. **Is audio affected by the watermarking process?**  
   Audio is not altered, so your existing audio track remains intact.  

3. **How large can my video be?**  
   This depends on your tier. For performance, it’s recommended to keep video sizes at a reasonable limit (e.g., under a few hundred MB).  

4. **Can the watermark be placed in corners or different positions?**  
   Currently, the API places the watermark in a standard position. Further customization may be added based on demand.  

5. **How quickly does the service process a typical video?**  
   Processing times vary based on video length and complexity, but most requests complete well within the 10-minute timeout window.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello[at]api.market.

Automatically embed a custom text watermark onto any video file. Fast server-side processing. Paid plans from $5/mo. Try it free on API.market.

AddWatermark – Brand & Protect Videos | From $5/mo | API.market