KONPRO JS SDK Quick Start

Integrate KONPRO's AI avatars and video services in your web apps with @konpro/js-sdk

The KONPRO JavaScript SDK (@konpro/js-sdk) makes it easy to integrate KONPRO's AI avatars and video services directly into your web applications. Use it to authenticate, call KONPRO APIs, and embed interactive experiences with just a few lines of code.

• npm: @konpro/js-sdk
• Package: https://www.npmjs.com/package/@konpro/js-sdk

For REST-first setup, see also Quick Start.

1. Installation

Install the SDK from npm:

npm install @konpro/js-sdk
# or
yarn add @konpro/js-sdk

2. Get Your API Key

1. Sign in to KONPRO Studio.
2. Go to Settings → API Keys.
3. Click Generate New Key and copy it.
4. Store it securely (do not commit it to Git or expose it in client-side code).

3. Initialize the SDK

In your app entry point (for example, src/index.ts or src/main.ts):

import { KonproClient } from '@konpro/js-sdk';

const konpro = new KonproClient({
  apiKey: process.env.KONPRO_API_KEY as string,
  baseUrl: 'https://api.konpro.ai', // default; override for custom environments
});

Make sure KONPRO_API_KEY is loaded from a secure environment variable.

4. List Avatars

Fetch available avatars to let users pick a character. This maps to the /v1/avatars endpoint under the hood.

const avatars = await konpro.avatars.list({
  scope: 'public', // or 'account'
  page: 1,
  limit: 20,
});

console.log(avatars.items);

5. Create an Avatar Video

Generate a video using a selected avatar, voice, and script:

const job = await konpro.videos.create({
  avatarId: 'avatar_123',
  voiceId: 'voice_en_female_1',
  script: 'Welcome to our product demo. Let me walk you through the main features.',
  aspectRatio: '16:9',
  outputFormat: 'mp4',
});

console.log('Video job created:', job.id);

Poll for completion:

const result = await konpro.videos.waitForCompletion(job.id);
console.log('Video URL:', result.url);

6. Embed a Real-Time Avatar Widget

Use the SDK to generate a signed configuration for a front-end widget (for example, in a React app):

const session = await konpro.sessions.create({
  avatarId: 'avatar_123',
  mode: 'realtime',
  metadata: { source: 'marketing-landing-page' },
});

// Pass `session.token` to your front-end widget

On the front end, your widget can connect to the session using the provided token (see the widget docs for implementation details).

7. Error Handling

The SDK throws structured errors when the API returns non-2xx responses:

try {
  const avatars = await konpro.avatars.list();
} catch (err: any) {
  console.error('KONPRO SDK error:', err.message, err.code, err.details);
}

Handle errors at the boundary of your routes / controllers to show helpful messages to users.

8. TypeScript Support

The KONPRO JS SDK is written with TypeScript types, so you get auto-complete and compile-time checks out of the box:

import type { CreateVideoRequest } from '@konpro/js-sdk';

const payload: CreateVideoRequest = {
  avatarId: 'avatar_123',
  voiceId: 'voice_en_female_1',
  script: 'Hello from KONPRO!',
};

9. Environments

By default the SDK points to the production API:

You can override this for staging or regional deployments:

const konpro = new KonproClient({
  apiKey: process.env.KONPRO_API_KEY!,
  baseUrl: 'https://api-staging.konpro.ai',
});

10. Next Steps

• API Reference: Full REST API docs and endpoint details: https://docs.konpro.ai/api
• More Examples: Check the examples section in the SDK README on npm/GitHub.
• Support: If you run into issues, contact us via KONPRO Studio support or your account representative.

This guide pairs well with Quick Start for deeper API reference and advanced guides.