Configuration

CreativeEngine.init() initializes the CE.SDK engine for headless operations in Node.js environments.

import CreativeEngine from '@cesdk/node-native';

const config = {
  license: process.env.CESDK_LICENSE || '',
};

const engine = await CreativeEngine.init(config);

This guide covers required and optional configuration properties, and runtime APIs for server-side CE.SDK usage with native bindings.

License Key#

CE.SDK is a commercial product and a license is required for production use. Without a license, CE.SDK runs in evaluation mode, which watermarks exports.

Request a license through IMG.LY Contact Sales.

const config = {
  license: process.env.CESDK_LICENSE || '',
};

const engine = await CreativeEngine.init(config);

Optional Configuration#

These properties customize engine behavior and are all optional.

Configuration Properties#

License Key#

The license key validates your CE.SDK subscription and removes watermarks from exports. Without a valid license, exports include a watermark.

const config = {
  license: 'YOUR_CESDK_LICENSE_KEY',
};

const engine = await CreativeEngine.init(config);

User ID#

Provide a unique user identifier for accurate Monthly Active User (MAU) tracking. This helps count users correctly when processing requests from different sources.

const config = {
  license: 'YOUR_CESDK_LICENSE_KEY',
  userId: 'user-123',
};

const engine = await CreativeEngine.init(config);

Custom Logger#

Replace the default console logging with a custom logger function. The logger receives a message string and an optional log level ('Info', 'Warning', or 'Error').

const config = {
  license: 'YOUR_CESDK_LICENSE_KEY',
  logger: (message, level) => {
    if (level === 'Error') {
      console.error('[CE.SDK]', message);
    }
  },
};

const engine = await CreativeEngine.init(config);

Render Device#

On macOS and Linux, the native bindings render on the platform’s GPU by default (Metal on macOS, EGL on Linux) and automatically fall back to CPU rendering when no compatible GPU is available. Use the device property to override this behavior: 'gpu' fails initialization if no GPU context can be created, and 'cpu' forces CPU rendering.

Windows renders on the CPU only. There, 'gpu' always fails and 'auto' selects the CPU.

const config = {
  license: 'YOUR_CESDK_LICENSE_KEY',
  device: 'cpu',
};

const engine = await CreativeEngine.init(config);

Licensed Codec Pack on Linux#

Download the Linux x86_64 codec pack from your licensing dashboard and extract it to $HOME/.local/share/cesdk-codecs for automatic discovery. To use a custom location, set the environment variable CESDK_LICENSED_CODEC_PACK to the extracted pack root before loading CE.SDK. This directory must contain the plugins/, presets/, and misc/ folders.

Set it in the shell:

CESDK_LICENSED_CODEC_PACK="/srv/cesdk-codecs" node index.mjs

Or set it in Node.js using process.env before importing CE.SDK:

process.env.CESDK_LICENSED_CODEC_PACK = '/srv/cesdk-codecs';
const { default: CreativeEngine } = await import('@cesdk/node-native');

Use a dynamic import here so the assignment runs first. With CommonJS, set the variable before require('@cesdk/node-native'). Restart the process after changing the path. See the Node Native setup guide for download and extraction instructions.

Runtime Settings#

After initialization, configure engine behavior using type-specific setting methods. Settings control features like double-click crop behavior and highlight colors.

engine.editor.setSettingBool('page/title/show', false);
const value = engine.editor.getSettingBool('page/title/show');

Exporting Results#

After processing a scene, export the result to a file. The engine’s block.export() method returns a Blob, matching the @cesdk/node API. Convert it to a Buffer before writing it to the file system.

import fs from 'fs/promises';

const blob = await engine.block.export(page, { mimeType: 'image/png' });
await fs.writeFile('./output.png', Buffer.from(await blob.arrayBuffer()));

Engine Disposal#

Clean up engine resources when done processing by calling engine.dispose(). Place this in a finally block to ensure cleanup even if errors occur.

try {
  // ... processing logic
} finally {
  engine.dispose();
}

API Reference#