Search
Loading...
Skip to content

Without UI (Headless)

Manual Download - Module
Manual Download - Global Variable
Without UI (Headless)

This guide walks you through integrating CE.SDK’s headless engine into a JavaScript project for programmatic image and video editing. By the end of this guide, you’ll have a functional CE.SDK instance running locally, allowing you to manipulate design elements without a UI.

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 (for example, 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).

Step 1: Set Up Your Project Structure#

Create the following folder and files:

/my-cesdk-project
  ├── index.html
  └── index.js

index.html#

Create a basic HTML file that loads your JavaScript module:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>CE.SDK Headless</title>
    <style>
      body {
        margin: 0;
        overflow: hidden;
      }
    </style>
  </head>
  <body>
    <!-- No UI needed in headless mode -->
    <script type="module" src="./index.js"></script>
  </body>
</html>

index.js#

This is where you’ll place your CE.SDK headless logic (no UI rendering) in the steps below.

Step 2: Integrate Into Your Application#

In your index.js, you first need to import the CreativeEngine module and initialize it with the appropriate configuration.

Import and Configure#

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

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


const config = {
  license: 'YOUR_LICENSE_KEY', // Replace with your CE.SDK license key
  baseURL:
    'https://cdn.img.ly/packages/imgly/cesdk-engine/1.59.2/assets',
};

Initialize the Engine#

Call the 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...
});

Step 3: Perform a Basic Operation#

Once initialized, you can use the engine’s API to create and manipulate scenes. Below is a breakdown of a basic 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, { mimeType: 'image/png' });
console.log('Export complete', blob);

5. Clean Up#

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

engine.dispose();

Step 4: Run the Project Locally#

Since you are using ES modules, you need an HTTP server that supports them. Run the following command:

Terminal window
npx serve

This will start a local development server available on localhost.

Step 5: Test the Integration#

  1. Open http://localhost:3000/ in your browser.
  2. The script will initialize the 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, { mimeType: '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: