Skip to content

Without UI (Headless)

Who is This Guide For?

This guide is for developers who:

  • Need to perform image and video editing operations programmatically without a UI.
  • Want to use CE.SDK’s headless engine for batch processing or creative automation.
  • Require a script-based approach for design generation.

What You’ll Achieve

  • Install and configure CE.SDK Engine.
  • Use the headless API to manipulate design elements.
  • Generate graphics or videos without rendering a UI.

Prerequisites

Before getting started, ensure you have:

  • Completed a previous CE.SDK Vanilla JS integration guide (e.g., Integrate CE.SDK as module).
  • Node.js installed, including npm (or npx) to run command-line tools.

Integrate into your application

To get started with CE.SDK in a headless setup (no UI rendering), you first need to import the CreativeEngine module and initialize it with the appropriate configuration.

Import and configure

Use the following code snippet to import the CE.SDK from the IMG.LY CDN and configure it with your license and asset base URL:

import CreativeEngine from 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.51.0/index.js';


const config = {
  license: 'YOUR_LICENSE_KEY', // Replace with a valid license key
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.51.0/assets',
};

Initialize the engine

Call the static init() method on CreativeEngine to initialize the SDK:

CreativeEngine.init(config).then(async engine => {
  console.log('CE.SDK Engine initialized');


  // You can now use the engine to perform creative operations...
});

Perform a simple operation

Once initialized, you can use the engine’s API to create and manipulate scenes. Below is a breakdown of a simple example that demonstrates core operations:

1. Create a scene

Scenes are the root containers for all creative content. In headless mode, no visual editor is shown—everything is controlled programmatically:

const scene = engine.scene.create();

2. Add a page

Pages represent visual containers (like canvases) within the scene. You must add at least one to define a workspace:

const page = engine.block.create('page');
engine.block.appendChild(scene, page);

3. Add a rectangle shape

You can create graphic blocks and assign shapes to them. In this case, a rectangle:

const rect = engine.block.create('graphic');
engine.block.setShape(rect, engine.block.createShape('rect'));
engine.block.appendChild(page, rect);

4. Export the scene

To generate an image output, export the scene as a PNG:

const blob = await engine.block.export(scene, 'image/png');
console.log('Export complete', blob);

5. Clean up

Always dispose of the engine once you’re finished to release resources:

engine.dispose();

Serve the Project Locally

Since we are using ES Modules, we need a local development server that supports them. Run the following command:

Terminal window
npx serve

This will start a local development server, typically available at http://localhost:3000

Test the Integration

  1. Open http://localhost:3000/ in your browser.
  2. The script will initialize CE.SDK Engine and programmatically generate and export a scene without UI interaction.
  3. Check the console for messages indicating a successful scene export.

Using the Headless API for Advanced Editing

1. Adding an Image Block

const imageBlock = engine.block.create('graphic');
const imageFill = engine.block.createFill('image');
engine.block.setFill(imageBlock, imageFill);
engine.block.setString(
  imageFill,
  'fill/image/imageFileURI',
  'https://img.ly/static/ubq_samples/imgly_logo.jpg',
);
engine.block.appendChild(page, imageBlock);

2. Adding Text to the Scene

const textBlock = engine.block.create('text');
engine.block.setString(textBlock, 'text/content', 'Hello, CE.SDK!');
engine.block.appendChild(page, textBlock);

3. Exporting the Scene as an Image

const exportedImage = await engine.block.export(scene, 'image/png');
console.log('Image Exported:', exportedImage);

4. Editing Videos in Headless Mode

const videoBlock = engine.block.create('graphic');
const videoFill = engine.block.createFill('video');
engine.block.setFill(videoBlock, videoFill);
engine.block.setString(
  videoFill,
  'fill/video/fileURI',
  'https://cdn.img.ly/assets/demo/v2/ly.img.video/videos/pexels-kampus-production-8154913.mp4',
);
engine.block.appendChild(page, videoBlock);

Troubleshooting & Common Errors

❌ Error: Module not found

  • Ensure you’re using type="module" in index.html.

❌ Error: Invalid license key

  • Verify that your license key is correct and not expired.

❌ Error: CE.SDK Engine is not defined

  • Ensure the CDN script is loaded before calling CreativeEngine.init().

Next Steps

Congratulations! You’ve successfully integrated CE.SDK Engine in headless mode. Next, explore advanced features: