# VideoOptimizer > VideoOptimizer is a professional, ad-free video hosting and delivery platform for > online shops, CMS-based websites and marketing teams, made and hosted in Europe > (GDPR-compliant). Upload a video once; it is encoded into an adaptive-bitrate > ladder and delivered over a global CDN through a white-label player that you > embed with one code snippet or integrate via a REST API. Built by ScaleCommerce. VideoOptimizer is a product of ScaleCommerce (https://scale.sc), a team with more than 15 years of experience building and operating high-performance online shops. Sign up for free at https://app.videooptimizer.eu/auth/register (a trial starts right away, no payment details needed). - App (sign up / sign in): https://app.videooptimizer.eu/ - Documentation: https://app.videooptimizer.eu/docs - API reference (interactive): https://api.videooptimizer.eu/ - OpenAPI spec (machine-readable): https://api.videooptimizer.eu/openapi.json - MCP server for AI assistants: https://api.videooptimizer.eu/api/v1/mcp (setup: https://app.videooptimizer.eu/docs/mcp) - Support: support@scale.sc ## Key facts - **What it is:** hosting, encoding and delivery of on-demand videos for websites and online shops (product videos, brand films, tutorials, hero/background videos), with a white-label player. Not a video community, no public channel pages. - **Not offered:** live streaming, DRM/content protection, advertising/monetisation, paid content or paywalls. - **Hosting & privacy:** developed, hosted and operated in Europe; no US servers; the player sets no tracking cookies. A data processing agreement (DPA/AVV) is available from support. - **Getting started:** free sign-up with a trial (one library, a limited number of videos); afterwards a paid plan. For prices and contract customers contact support@scale.sc. - **Uploads:** any common video format (MP4, MOV, MKV, WebM, …), files up to 20 GB (smaller during the trial), via the app, the REST API (incl. remote-URL ingest) or the MCP server. - **Playback:** adaptive HLS (H.264, up to 4K) via the hosted iframe player or an inline video.js snippet; works in all current browsers incl. iOS/Safari. Subtitles (WebVTT) and responsive AVIF/WebP preview images included. - **Stable URLs:** embed, poster and HLS URLs never change — replacing or re-encoding a video keeps every existing embed working. ## Why VideoOptimizer The alternative to YouTube/Vimeo embeds and to static MP4 files on a web server — built for commerce and brand sites, not for entertainment: - **No ads, no third-party recommendations, no foreign branding.** On YouTube, competitor products are recommended after a product video; on Vimeo their logo appears. VideoOptimizer's player is white-label and keeps visitors on your page. - **GDPR-compliant, made in Europe.** Developed, hosted and operated in Europe, no US servers. - **Automatically optimised for every device.** A single MP4 is either too large for mobile or too low quality for desktop. VideoOptimizer encodes several quality levels (360p up to 4K/2160p) and streams adaptively (HLS), so playback starts fast and does not buffer. - **Your player, your branding.** Colours, controls, autoplay, loop, mute and thumbnail are configurable per organization, library or video. ## Features - **Media library**: upload (drag & drop, multiple files, multi-gigabyte files directly to storage), organise videos in libraries, tag them, track storage and traffic. - **Adaptive streaming**: HLS master playlist plus per-resolution MP4 renditions; the player picks the right quality for the viewer's screen and connection. - **Encoding**: H.264 for streaming and the hosted player (maximum compatibility); H.265, AV1 and VP9 can be added per library as extra MP4/WebM files for custom players. HDR sources are tone-mapped to SDR, interlaced sources deinterlaced, audio mixed down to stereo. - **Picture quality per library**: `performance` (default — compact files, fast start) or `quality` (finer detail for fabrics, glitter, stone; about 2.5–3× the traffic). - **Global CDN delivery** for video and image traffic; preview images are served as AVIF/WebP to browsers that support them. - **Subtitles**: languages per organization, SRT/WebVTT upload, subtitle tracks inside uploaded files are taken over automatically, browser editor, `?cc=` embed parameter. - **Embeddable player**: iframe embed or inline video.js snippet, responsive for every aspect ratio (16:9, 9:16, 1:1, 21:9), thumbnails ("Vorschaubild") selectable from auto-generated frames or uploaded; reusable player presets. - **Replace a video in place**: upload a new file and every existing embed keeps working. - **Analytics**: player loads, views, traffic and storage per organization, library and video. - **Teams**: multiple users per organization with owner/admin/member roles and fine-grained permissions; switch between organizations. - **Social publishing** to YouTube, Instagram and TikTok is in preparation (not available yet). - **Developer platform**: REST API (v1) with organization or personal tokens, signed webhooks, remote-URL ingest, your own key/value metadata per video (e.g. a CMS asset ID, filterable), an MCP server for AI assistants, OpenAPI spec and this llms.txt. ## Integrations - Official plugins: Shopware (https://github.com/ScaleCommerce/videooptimizer-shopware) and Sulu CMS (https://github.com/ScaleCommerce/videooptimizer-sulu). - Works with any shop or CMS via the embed code (WordPress, Webflow, Shopify, Oxid, Magento, …) or via the REST API for headless setups and custom workflows. ## Docs - [Documentation overview](https://app.videooptimizer.eu/docs): guides for developers and content teams. - [Embed guide](https://app.videooptimizer.eu/docs/embed): embedding videos into a CMS or shop without code. - [Showcase](https://app.videooptimizer.eu/docs/showcase): live demos of every embed pattern (lightbox with sound, gallery, background video, portrait formats, product video, JavaScript API). - [Developer guide](https://app.videooptimizer.eu/docs/developers): step-by-step API integration with cURL and JavaScript examples. - [Team & permissions](https://app.videooptimizer.eu/docs/permissions): roles and grantable permissions. - [AI assistants (MCP)](https://app.videooptimizer.eu/docs/mcp): connect Claude Code, Cursor, VS Code, Claude Desktop, OpenCode, Codex CLI, Gemini CLI, Hermes Agent or Unsloth Studio to the MCP server — token, client config, tools, example prompts. - [Subtitles](https://app.videooptimizer.eu/docs/subtitles): subtitle languages, SRT/WebVTT upload, tracks inside video files, editor, `?cc=` embed parameter. - [Picture quality](https://app.videooptimizer.eu/docs/quality): per-library quality mode (`performance` vs. `quality`), traffic effect, switching, API. - [API reference](https://api.videooptimizer.eu/) and [OpenAPI spec](https://api.videooptimizer.eu/openapi.json). ## API overview The REST API lets you upload, manage and embed videos programmatically from any backend, shop or CMS. All data is scoped to the organization that owns the API token. Base URL for all requests: https://api.videooptimizer.eu/api/v1 ## Authentication Every request (except the public Media and Embed endpoints) needs an API token. It looks like `vp_…`, is shown only once, and is sent as a Bearer token: Authorization: Bearer vp_your_token_here There are two token kinds — both use the same `vp_…` format and Bearer header: - **Organization token** (recommended for plugins / server integrations): created by an org admin under **Integrations → API tokens** (or by a superadmin for any organization from the admin area). Not tied to any person, grants full media access (all libraries + videos of the organization), and keeps working when staff change. A name is mandatory and shows up in the audit log. - **Personal token**: created by any user under **Account → API tokens**. Bound to that user + organization and carries their live permissions (permission changes take effect on the next request). Both can have an optional expiry and can be revoked at any time. ## Conventions - Successful responses wrap the payload: `{ "data": … }`. - Errors return `{ "statusCode": , "message": "" }` with the matching HTTP status. - Libraries are addressed by their UUID `id`; videos by their `uuid`. - Custom request headers use hyphens, never underscores (`x-library-id`). - Uploads are asynchronous. After upload, poll `GET /videos/{uuid}` until `status` is `"ready"` (or use the boolean `ready`). Status values: `processing`, `ready`, `failed`. A `failed` video carries a human-readable `error` (e.g. a remote-URL download error); it is `null` while `processing`/`ready`. - `poster_url` (and every `posterSrcset` entry) is the ACTIVE poster — the uploaded custom poster when one is active, otherwise the picked thumbnail frame. It is a STABLE, direct-CDN URL fixed per video that never changes — store it once, use it directly in ``/`poster`; when the poster is later changed the SAME URL serves the new image (the cache is purged on change). The image CDN answers the same `.jpg` URL with AVIF or WebP when the browser accepts it (JPEG otherwise); poster URLs stored earlier on the library CDN host keep working. This is the image to show before playback. Bind `posterSrcset` to a responsive `` (480/640/1280/1920, plus 2560/3840 for large source images; only widths up to the source); `poster_url` is the single medium-size default. - `thumbnail_url` is different: it is always the representative thumbnail FRAME (never the custom poster — use `poster_url` for the active preview) and points at that frame's own direct-CDN key, so it changes if a different thumbnail is selected. An uploaded custom poster becomes the active poster as soon as it is processed (`poster/select` switches back to a frame); the uploaded image itself is always at `poster.custom_url` (preview only). All image traffic stays on the CDN. - Rate limits (sliding 60 s window): 600 read requests (GET) and 120 write requests per minute per token; 1,200 requests per minute per IP for the public embed and media endpoints. On `429` respect the `Retry-After` and `X-RateLimit-*` response headers. Expensive calls have an extra hourly limit: creating videos (`POST /videos`, `POST /videos/upload/initiate`) 120/hour, subtitle uploads 120/hour, `POST /libraries/{id}/reprocess` 5/hour. - High traffic: don't call the API on every page view of a shop/CMS. Cache responses (a video's embed config and URLs only change when the video changes), store the stable `embed_url`/`hls_url`/`poster_url`/`thumbnail_url` once, use webhooks instead of polling. Public embed and media responses may be cached up to 60 s by browsers/CDNs. - List endpoints (libraries, videos) use cursor pagination: `?limit=` (default 50, max 100) and `?cursor=` (opaque, from a previous response). They return `{ data, pagination: { next_cursor, has_more } }` — pass `next_cursor` back as `?cursor=` to fetch the next page; `has_more` is `false` (and `next_cursor` is `null`) on the last page. ## Endpoints ### Libraries - `GET https://api.videooptimizer.eu/api/v1/libraries` — list all libraries in your organization (paginated, see Conventions) - `POST https://api.videooptimizer.eu/api/v1/libraries` — create a library (JSON body: `name` required; optional `description`, `resolutions`, `codec`, `encoding_quality`). CDN delivery is provisioned automatically. - `GET https://api.videooptimizer.eu/api/v1/libraries/{id}` — get one library - `PATCH https://api.videooptimizer.eu/api/v1/libraries/{id}` — update `name`/`description`/`codec`/`resolutions`/`encoding_quality` - `DELETE https://api.videooptimizer.eu/api/v1/libraries/{id}` — delete a library and all its videos - `POST https://api.videooptimizer.eu/api/v1/libraries/{id}/reprocess` — re-queue encoding for every video in the library (body `{"force": true}` re-encodes finished renditions too — needed after changing `encoding_quality`) - `GET https://api.videooptimizer.eu/api/v1/libraries/{id}/videos` — list videos in a library (paginated, see Conventions) A library carries `encoding_quality`: `performance` (default — compact files, fast start, least traffic) or `quality` (finer detail for fabrics, glitter, stone — roughly 2.5–3× the file size and CDN traffic). A library object carries `media_managed` (boolean). When `true`, upload, poster/thumbnail selection, and reprocess are available; when `false` those write endpoints return 400 (the library is delivery-only). Check it before offering those actions instead of reacting to a 400. A library also carries `available_codecs` and `available_resolutions` — the option keys your organization may enable right now. Setting `codec`/`resolutions` (on create or update) to a value outside this set returns 400 (options already active on the library are grandfathered). See Encodings. ### Encodings - `GET https://api.videooptimizer.eu/api/v1/encodings` — list the codecs and resolutions your organization may enable, each with `{ key, label, access, available }`. `access: "addon"` + `available: false` = a paid add-on not yet unlocked for your organization. Options disabled platform-wide are omitted. ### Videos - `GET https://api.videooptimizer.eu/api/v1/videos` — list all videos in your organization, newest first (paginated, see Conventions). Optional `?library_id=` restricts to one library; optional `?tags=a,b` returns only videos carrying ALL listed tags (also on `GET /libraries/{id}/videos`; max 20 names, an invalid name returns 400 instead of being ignored); optional `?metadata[]=` returns only videos with exactly that metadata value (see **Metadata**). - `POST https://api.videooptimizer.eu/api/v1/videos` — create a video. Two variants: (1) `multipart/form-data` with a `file` field; headers `x-library-id` (required, target library UUID) and `x-title` (optional), `x-tags` (optional, comma-separated, each name percent-encoded UTF-8, e.g. `Pr%C3%A4sentation,2026`). (2) `application/json` with `{ library_id, source_url, title?, tags?, metadata? }` — remote-URL ingest, see below. Returns `{ data: { uuid, status: "processing" } }`. - `POST https://api.videooptimizer.eu/api/v1/videos/upload/initiate`, `POST https://api.videooptimizer.eu/api/v1/videos/upload/complete` — presigned multipart upload, **recommended for large files** (see **Large file uploads** below). Selfhosted libraries only. - `GET https://api.videooptimizer.eu/api/v1/videos/{uuid}` — get a video: `metadata`, `status`/`ready`, `error` (reason when failed, else null), `duration`, `resolution`, `views`, `poster_url`, `thumbnail_url`, `hls_url`, `embed_url`, `options`, `renditions` (only the qualities actually delivered — renditions above the source resolution are skipped, never upscaled, so this can be fewer than the library's configured `resolutions`). - `PATCH https://api.videooptimizer.eu/api/v1/videos/{uuid}` — update `title`, player `option` (responsive, autoplay, preload, loop, muted), `tags` (string array, replaces the whole set; `[]` clears it) and/or `metadata` (merged: keys you send are set, a key with `null` is removed, `"metadata": null` removes all); fields you leave out stay unchanged - `DELETE https://api.videooptimizer.eu/api/v1/videos/{uuid}` — delete a video - `GET https://api.videooptimizer.eu/api/v1/videos/{uuid}/thumbnails` — list auto-generated thumbnails as `{ data: { thumbnails: [{ index, url }] } }` - `POST https://api.videooptimizer.eu/api/v1/videos/{uuid}/thumbnail` — set the active thumbnail (JSON body: `thumbnailIndex` 0–9) - `POST https://api.videooptimizer.eu/api/v1/videos/{uuid}/poster/initiate|complete|select`, `DELETE …/poster` — manage a custom poster image (advanced: presigned upload flow) ### Metadata Store your own key/value data on a video — e.g. the space, environment and asset ID of the CMS entry it belongs to — and find the video by it, without abusing tags: - Set it on create (`metadata` in the JSON body of `POST /videos` with `source_url`, or on `upload/complete`; for a multipart upload set it afterwards) or with `PATCH /videos/{uuid}`, e.g. `{"metadata": {"contentful_asset_id": "4ycPbMkEPCPWDBVVuJSVJy", "contentful_environment": null}}` — merged: keys you send are set, `null` removes a key, other keys stay; `"metadata": null` removes all. - Find videos with `GET https://api.videooptimizer.eu/api/v1/videos?metadata[contentful_asset_id]=4ycPbMkEPCPWDBVVuJSVJy` (also on `GET /libraries/{id}/videos`). Up to 5 `metadata[…]` filters per request, combined with AND (and with `tags`, `library_id`). Percent-encode the value. - Every video object (REST, webhooks, MCP) carries `metadata` as an object with sorted keys (`{}` when none). - Rules: max 10 keys per video; keys 1–40 characters of lower-case `a-z`, `0-9`, `_`, `.`, `-` (starting with a letter or digit); values strings of 1–64 characters, no control characters, leading/trailing spaces trimmed, otherwise stored exactly as sent. Matching is **exact and case-sensitive** (`ABC` does not find `abc`). **Not unique** — the same value on several videos is allowed, so a filter can return more than one video. Invalid input is a 400 with `data.code` (`metadata_invalid_key`, `metadata_invalid_value`, `metadata_limit`, `metadata_invalid`), never silently dropped. ### Savings - `GET https://api.videooptimizer.eu/api/v1/savings` — what VideoOptimizer saves compared to serving the original files: `compression` (originals vs. the largest delivered version, `reduced_percent`), and — when CDN traffic data is available — `range` (needs `?from=YYYY-MM-DD&to=YYYY-MM-DD`, max. 366 days) and `all_time`, each with `delivered_bytes`, `estimated_original_bytes`, `saved_bytes`, `saved_percent`. Optional `?library_id=` or `?video_uuid=`. Bandwidth figures are estimates: delivered video data scaled by original ÷ largest H.264 version (at least 1); thumbnails and playlists count without a saving; no saving is counted before October 2026. ### Tags - `GET https://api.videooptimizer.eu/api/v1/tags` — list your organization's tags as `{ name, video_count }`. Tags are organization-wide (shared by all libraries). Every video carries `tags` (names, alphabetical). Names: 1–50 characters, no commas; max 20 per video, 500 per organization. Unknown names are created automatically when assigned. Matching is case-insensitive: a tag keeps the spelling it was first created with, and a later variant (e.g. `promo` for `Promo`) attaches the existing tag — send one consistent spelling to control how it is stored. ### Subtitles - `GET https://api.videooptimizer.eu/api/v1/subtitle-languages` — your organization's subtitle languages as `{ code, label, video_count }` (BCP 47 code, label shown in the player menu) - `POST https://api.videooptimizer.eu/api/v1/subtitle-languages` — add one: JSON `{ code, label? }` (needs `library:edit`; without `label` the language's own name is used). The code cannot be changed later. - `DELETE https://api.videooptimizer.eu/api/v1/subtitle-languages/{code}` — remove a language (needs `library:edit`); `409 subtitle_language_in_use` while videos still have subtitles in it — delete those per video first. - `GET https://api.videooptimizer.eu/api/v1/videos/{uuid}/subtitles` — subtitles of a video as `{ language, label, kind, is_default, cue_count, source_format, origin, updated_at }`. Subtitle tracks inside an uploaded video file (MKV/MP4/MOV text tracks, CEA-608 captions) are taken over automatically for your organization's languages (`origin: "embedded"`); a separately uploaded file always wins - `POST https://api.videooptimizer.eu/api/v1/videos/{uuid}/subtitles` — upload: `multipart/form-data` with `file` (.srt or .vtt, max. 2 MB), `language` (one of your subtitle languages), optional `kind` (`subtitles` | `captions`) and `is_default` (`true`/`false`, at most one per video). Replaces an existing file of that language in place; SRT is converted to WebVTT, malformed cues are skipped (`skipped_cues`). - `GET https://api.videooptimizer.eu/api/v1/videos/{uuid}/subtitles/{language}` — download the stored WebVTT file - `DELETE https://api.videooptimizer.eu/api/v1/videos/{uuid}/subtitles/{language}` — delete one language - Playback: the embed payload carries `tracks` (`{ src, srclang, label, kind, default }`, CDN URLs) — add them as `` elements with `crossorigin="anonymous"` on the `