Skip to main content

Deprecating the "insert" Parameter in Layers API

· 3 min read
Stefan Benicke
Stefan Benicke
Senior Developer @ Eyeson

Starting September 1st, the Eyeson API's layers endpoint will no longer support the insert parameter. While file and url parameters will continue to work unchanged, the legacy insert option is being officially removed. Though it's been omitted from the documentation for a while, this formal announcement aims to help any long-term users relying on it to transition smoothly.

Why the Change?​

The insert parameter was originally introduced to make it easy to display simple overlays by automatically generating a grey, translucent background with the provided text inside. It was a convenient shortcut, requiring no design work or external assets.

However, as developer needs evolved, so did our API. The insert parameter is now being retired in favor of a much more powerful and flexible alternative: SVG overlays.

Your Best Option Going Forward: SVG Overlays​

With SVG, you can easily replicate the same translucent text box style that insert used - but you're not limited to it:

  • Position the overlay anywhere in the video frame
  • Adjust size, and colors to match your brand or UI needs
  • Add icons, shapes, or even dynamic data if needed
  • SVGs are lightweight, scalable, and rendered server-side by Eyeson - just like the old insert

Whether you're sending an SVG via file or referencing one hosted via url, the setup is straightforward. And because SVG is just XML, it's easy to generate dynamically from backend code or templates.

Check out our dedicated blog post on SVG support and how to implement it here: Using SVG with Eyeson Layers

Example: Recreating the Old "insert" Style with SVG​

With the @eyeson/node-svg-layer Node.js plugin, you can easily generate a styled SVG overlay that mimics the default insert look:

import Eyeson from '@eyeson/node';
import EyesonSvgLayer from '@eyeson/node-svg-layer';

const eyeson = new Eyeson();
const layer = new EyesonSvgLayer();

const text = '...';
const fontSize = 16;
const bold = false;
const fontColor = 'black';
const x = 240;
const y = 360;
const width = 800;
const maxHeight = 360;
const padding = 10;
const lineHeight = 20;
const radius = 5;
const color = 'grey 60%';

layer.addMultilineTextBox(text, fontSize, bold, fontColor, x, y, width, maxHeight, padding, lineHeight, radius, color);

const user = await eyeson.getUser(accessKey);
await user.sendLayer(layer);

This creates:

  • A centered text box
  • Black text on a grey translucent background
  • Padding and border radius to match the legacy style

For more customization tips and advanced dynamic overlays, check out the full documentation.

Final Note​

We're committed to providing a developer-friendly, future-ready platform. SVG gives you the flexibility that insert never could - and we're confident your overlays will look better and work more reliably with this update.

As always, if you need help migrating or want to share feedback, don’t hesitate to reach out via GitHub.

Thanks for building with Eyeson!