Quickstart

Watermark your first image with one HTTP request — from zero to a downloadable result in about five minutes.

This guide watermarks an image with a single synchronous call. You send a source URL, Fotovid processes it, and you get the result back in the same response — no polling, no webhooks.

Get an API key

Create a key in the Fotovid dashboard under Account → API Keys. The full key is shown once at creation, in the form p6_<key_id>:<secret> — copy it now and store it somewhere safe.

See Authentication for the details.

Make your first call

Send a POST to /v1/image/watermark with a publicly reachable source_url and your watermark params.

curl -X POST https://api.fotovid.co/v1/image/watermark \
  -H "Authorization: Bearer p6_<key_id>:<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://cdn.example.com/photo.jpg",
    "params": { "watermark_type": "text", "text": "Fotovid.co", "position": "bottom-right" }
  }'

const res = await fetch("https://api.fotovid.co/v1/image/watermark", {
  method: "POST",
  headers: {
    Authorization: "Bearer p6_<key_id>:<secret>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source_url: "https://cdn.example.com/photo.jpg",
    params: { watermark_type: "text", text: "Fotovid.co", position: "bottom-right" },
  }),
});

const result = await res.json();
console.log(result.url);

import requests

res = requests.post(
    "https://api.fotovid.co/v1/image/watermark",
    headers={"Authorization": "Bearer p6_<key_id>:<secret>"},
    json={
        "source_url": "https://cdn.example.com/photo.jpg",
        "params": {"watermark_type": "text", "text": "Fotovid.co", "position": "bottom-right"},
    },
)
print(res.json()["url"])

Read the result

A synchronous call returns 200 OK with a flat body. There is no status field — a 200 response is success.

{
  "id": "01JABCDEFGHJKMNPQRSTVWXYZ",
  "type": "image.watermark",
  "url": "https://tempfile.fotovid.co/i/<hex>.webp",
  "expires_at": "2026-06-10T12:00:00Z"
}

url is a time-limited download link to your watermarked image. Fetch it before expires_at (outputs are retained for 7 days).

The output defaults to WebP. Override it with params.output_format (webp | jpeg | png) and params.quality (1–100). The full parameter list is in the watermarking guide.

Synchronous calls are meant for small, fast jobs (roughly a 10-second budget, source images up to 128 MiB). For large or long inputs — or if a sync call returns 413, 409, or 504 — use the asynchronous task API instead:

curl -X POST https://api.fotovid.co/v1/tasks \
  -H "Authorization: Bearer p6_<key_id>:<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "image.watermark",
    "source_url": "https://cdn.example.com/photo.jpg",
    "params": { "watermark_type": "text", "text": "Fotovid.co" }
  }'

This returns 201 with status: "starting"; then either poll GET /v1/tasks/{id} until it reaches succeeded or supply a webhook URL to be notified. The output there lives in outputs[].url.

Learn when to use each in Synchronous vs. asynchronous, and the full async flow in Tasks & polling.

Quickstart

Get an API key

Make your first call

Read the result

Handling larger files

Next steps

Authentication

Watermarking

Errors

API reference

On this page