Search
Loading...
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.
  • A valid CE.SDK license key (Get a free trial).

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.52.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.52.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: