JavaScript API Bindings - Edge Impulse Documentation

The edge-impulse-api library contains bindings to the Edge Impulse API for Node.js and browser environments. It lets you automate anything that you can do through the Studio UI (and much more).

Installation

Install the package via npm (also see the npm package page):

npm install edge-impulse-api

Browser CDN Links

For browser-based environments, you can include the API bindings directly from the Edge Impulse Studio CDN:

Development / Debugging: https://studio.edgeimpulse.com/api-bindings/browser/edge-impulse-api.js
Minified Production Version: https://studio.edgeimpulse.com/api-bindings/browser/edge-impulse-api.min.js
TypeScript Definition File: https://studio.edgeimpulse.com/api-bindings/browser/edge-impulse-api.d.ts

Examples

Instantiating the Library

JavaScript (CommonJS)

const EdgeImpulseApi = require('edge-impulse-api').EdgeImpulseApi;
const api = new EdgeImpulseApi();

TypeScript (ES Modules)

import { EdgeImpulseApi } from 'edge-impulse-api';
const api = new EdgeImpulseApi();

Authenticating

API Key

API Keys grant access to a single project and have a permission scope.

const EdgeImpulseApi = require('edge-impulse-api').EdgeImpulseApi;

(async () => {
    const api = new EdgeImpulseApi();
    await api.authenticate({
        method: 'apiKey',
        apiKey: 'ei_...', // your API key here
    });
})();

Username / Password (JWT)

Username and password authentication gives access to every project in your account. Where possible, use API keys instead. You can cache the JWT token (typically valid for 30 days, unless reconfigured by your enterprise administrator) to avoid putting your credentials directly in code.

const EdgeImpulseApi = require('edge-impulse-api').EdgeImpulseApi;

(async () => {
    try {
        const api = new EdgeImpulseApi();

        const jwtToken = await api.login.login({
            username: 'myusername',
            password: 'mypassword'
        });

        await api.authenticate({
            method: 'jwtToken',
            jwtToken: jwtToken.token || '',
        });
    }
    catch (ex) {
        // check token expiration
        const tokenExpired = (ex.message || ex.toString()).indexOf('Your JWT token has expired') > -1;
        if (tokenExpired) {
            console.log('Token was expired, need to re-log in', ex);
            process.exit(1);
        }

        console.log('Failed to make a request', ex);
        process.exit(1);
    }
})();

Calling API Functions

The following example lists active projects and retrieves project information.

let projects = await api.projects.listProjects();
console.log('all projects', projects.projects.map(p => {
    return {
        id: p.id,
        name: p.name,
        owner: p.owner,
    };
}));

let projectInfo = await api.projects.getProjectInfo(projects.projects[0].id);
console.log('projectInfo', projectInfo);

Running Jobs

Long-running API calls (such as retraining a network) return a job. Here is how you retrain a Keras model block, wait for the job to complete, and print the real-time logs:

(async () => {
    try {
        const PROJECT_ID = 12345;

        let impulseRes = await api.impulse.getImpulse(PROJECT_ID);
        if (!impulseRes.impulse) {
            throw new Error('Project has no impulse');
        }
        let kerasBlock = impulseRes.impulse.learnBlocks.find(x => x.type.indexOf('keras') > -1);
        if (!kerasBlock) {
            throw new Error('Failed to find a Keras block in ' + JSON.stringify(impulseRes.impulse, null, 4));
        }

        // grab the config
        let kerasConfig = await api.learn.getKeras(PROJECT_ID, kerasBlock.id);

        // and retrain with same config
        let trainJob = await api.jobs.trainKerasJob(PROJECT_ID, kerasBlock.id, kerasConfig);
        console.log('Created train job with ID', trainJob.id);

        await api.runJobUntilCompletion({
            type: 'project',
            projectId: PROJECT_ID,
            jobId: trainJob.id,
        }, data => {
            process.stdout.write(data);
        });

        console.log('Train job completed');
    }
    catch (ex) {
        console.log('Failed to make a request', ex);
        process.exit(1);
    }
})();

Browser Integration

Simple Browser Example

The following is a complete HTML and JavaScript example using the Edge Impulse API bindings bundle in the browser:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Browser test</title>
</head>
<body>
    <div id="project">Nothing yet</div>
    <div id="user"></div>
    <pre id="job-output"></pre>

    <script src="https://studio.acc2.edgeimpulse.com/assets/7e353e8d99158a6915072395386421ea6b2fe40f/studio-api/studio-api-bundle.js"></script>
    <script>
        (async () => {

            const api = new EdgeImpulseApi({
                endpoint: 'http://localhost:4800'
            });

            const token = await api.login.login({
                username: 'selenium69_mobile_client',
                password: 'PF8wPcSSp9DGcKEy',
            });

            if (!token.token) {
                throw new Error(`token is null`);
            }

            await api.authenticate({
                method: 'jwtToken',
                jwtToken: token.token,
            });

            let user = await api.user.getCurrentUser();
            console.log('user', user.name);
            document.querySelector('#user').textContent = user.name;

            await api.authenticate({
                method: 'apiKey',
                apiKey: 'ei_2f91beed7dd692e9380c11c790525decc0cd2b43adb09567'
            });

            const projects = (await api.projects.listProjects()).projects;
            const project = (await api.projects.getProjectInfo(projects[0].id)).project;
            console.log('project', project.owner + ' / ' + project.name);
            document.querySelector('#project').textContent = project.owner + ' / ' + project.name;

            console.log('Starting job for project', project.owner, '/', project.name);

            let impulseRes = await api.impulse.getImpulse(project.id);
            if (!impulseRes.impulse) {
                throw new Error('Project has no impulse');
            }
            let kerasBlock = impulseRes.impulse.learnBlocks.find(x => (x.type).indexOf('keras') > -1);
            if (!kerasBlock) {
                throw new Error('Failed to find a Keras block in ' + JSON.stringify(impulseRes.impulse, null, 4));
            }

            // grab the config
            let kerasConfig = await api.learn.getKeras(project.id, kerasBlock.id);

            // and retrain with same config
            let trainJob = await api.jobs.trainKerasJob(project.id, kerasBlock.id, kerasConfig);
            console.log('Created train job with ID', trainJob.id);

            await api.runJobUntilCompletion({
                type: 'project',
                projectId: project.id,
                jobId: trainJob.id,
            }, data => {
                console.log(data);
                document.querySelector('#job-output').textContent += data;
            });

            console.log('Train job completed');
        })();
    </script>
</body>
</html>

TypeScript Integration

When using the browser bindings in a TypeScript project, you can get type safety for the global EdgeImpulseApi class by referencing the declaration file edge-impulse-api.d.ts using a triple-slash directive at the top of your TypeScript file:

/// <reference path="path/to/edge-impulse-api.d.ts" />

This directive instructs the TypeScript compiler to include type definitions for the global EdgeImpulseApi and window.EdgeImpulseApi variables, allowing type-safe interaction without needing an import statement.

​Installation

​Browser CDN Links

​Examples

​Instantiating the Library

​Authenticating

​API Key

​Username / Password (JWT)

​Calling API Functions

​Running Jobs

​Browser Integration

​Simple Browser Example

​TypeScript Integration