# Ultron AI SDK

Installation

Via npm

npm install ultron-ai-sdk

Quick Start

// Import the SDK
    import {SceneCanvas, Character} from 'ultron-ai-sdk';        
        
    let sceneCanvas
    let character
    
    const init = async() => {
        sceneCanvas = new SceneCanvas('target-html-element')
        const initializationSetting= {
            avatarId: "AVATAR_ID",       // AvatarId and Request Id are same
            config:{
                apiKey: "YOUR_ULTRON_API_KEY"
            },
            options:{
                alwaysListen: false // For Push to talk conversation
            }
        }
        await sceneCanvas.init(initializationSetting)
        character = sceneCanvas.character
                    
    }
    init()

In HTML Via CDN like jsDelivr.

<script type="importmap">
        {
          "imports": {
            "ultron-ai-sdk": "https://cdn.jsdelivr.net/npm/ultron-ai-sdk@1.0.4/dist/index.mjs?module"            
          }
        }
</script>

<script type="module">
    import {SceneCanvas, Character} from 'ultron-ai-sdk';        
        
    let sceneCanvas
    let character
    
    const init = async() => {
        sceneCanvas = new SceneCanvas('target-html-element')
        const initializationSetting= {
            avatarId: "AVATAR_ID",       // AvatarId and Request Id are same
            config:{
                apiKey: "YOUR_ULTRON_API_KEY"               // Not required if you can create and access "sessionId" 
                // sessionId: "SESSION_ID_FOR_CURRENT_USER" // Recomended method for secure access
            },
            options:{
                hideClickMessage: true //remove default "Click message" on the avatar
                alwaysListen: false    // For Push to talk conversation
            }
        }
        await sceneCanvas.init(initializationSetting)
        character = sceneCanvas.character

        // Use "character" object to call various methods like .chat() or .say()

        // character.say("Hello world")
        // character.chat("Please introduce yourself")

        //IMPORTANT --->
        // User interaction like click is necessory for the talking of the Avatar to work due to inbuilt security in variuos browser
                    
    }
    init()  // You can also call this on user interaction like clicking on support/chat icon.

</script>

Quick Demo

Check out our website for demo at: 🔗Talk to Avatar in metabrix website

Target HTML Element

<div id="target-html-element"></div>

API Reference

Initialization

const sceneCanvas = new SceneCanvas('target-html-element')
sceneCanvas.init({sessionId: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxx"})

Configuration Options

| Option | Description | |-------------|--------------| | sessionId (optional) | Session Id obtained using API key | | apiKey | You ultron key which can be found in your profile in Ultron App |

API key (apiKey)

To get API key of your ultron account follow the steps below

STEP 1: Click on account at top right corner

STEP 2: Select API key from dropdown

STEP 3: Copy your API key

Session Id (sessionId)

🔑 Create Session API

This API allows you to create a new session.

📌 Endpoint

POST /session/create

🔧 Headers:

| Key | Value | |-----------|-----------------| | x-api-key | your_api_key | | Content-Type | application/json |

📤 Request Body:

{
    "expiresIn": "100",
    "requestID": "xxxxx"
}

Response:

{
  "sessionId": "string",
  "status": "string"
}

async function createSession(apiKey, requestID, expiresIn) {
    const response = await fetch('https://api.ultronai.me/session/create', {
        method: 'POST',
        headers: {
            'x-api-key': apiKey,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ requestID, expiresIn })
    });

    const data = await response.json();
    console.log('Session Created:', data);
}

createSession('your_api_key', '123', 10);

// Use this sessionId in the SDK in your Web App
// Call this method on your server side for security and avoid exposing your API key

Note: Please use the method above to get session id on your server side for a secure workflow

Options

Always listen

Makes the character listen all the time once click for continous conversation (voice to voice)

• alwaysListen: Boolean - The unique identifier for the avatar

Hide default click message

Hides the default text message on the avatar to prompt user to click as an initial click is required for any audio to play in any browser

• hideClickMessage: Boolean - The unique identifier for the avatar

Core Methods

loadAvatar(avatarId)

Loads a specific avatar into the container.

• avatarId: String - The unique identifier for the avatar

AvatarId

To get avatarId follow the steps below

Step 1: Open the desired avatar in ultron app (app.ultronai.me)

Click share on top right corner

Step 1: Open the desired avatar in ultron app (app.ultronai.me)

Step 2: Select the avatar id value as from share url

Audio Input Device Settings

// to get all microphone input devices
const devices = ultronSDK.getAudioInputDevices()

// You can also use the devices to allow user to choose from the list

let myDevice = devices.find(device=> device.label.includes("My_preffered_device_name"))

// to set the desired Audio input device
if(myDevice)
ultronSDK.setAudioInputDevice(myDevice.deviceId)

Browser Support

✅ Chrome (latest)
✅ Firefox (latest)
✅ Safari (latest)
✅ Edge (latest)

Requirements

• WebGL-enabled browser
• JavaScript enabled
• Minimum screen resolution: 800x600

Best Practices

• Always initialize the SDK with a valid API key
• Implement error handling for load failures
• Clean up resources when removing the avatar
• Optimize container size for better performance
• Test across different browsers and devices

Examples

Basic Implementation

    import {SceneCanvas, Character} from 'ultron-ai-sdk';        
        
    let sceneCanvas
    let character
    
    const init = async() => {
        sceneCanvas = new SceneCanvas('target-html-element')
        const initializationSetting= {
            avatarId: "AVATAR_ID/REQUEST_ID",
            config:{
                sessionId: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxx"
            },
            options:{
                alwaysListen: false // For Push to talk conversation
            }
        }
        await sceneCanvas.init(initializationSetting)
        character = sceneCanvas.character
                    
    }
    init()

Chat with character using AI

// once you have the "character" object from sceneCanvas after init() you can use it to chat

character.chat("your text query to AI")

//This will generate a response from AI as per Avatar backstory and character will speak the response

Make the character say

character.say("your text that character will speak")

// This will simply make the character speak the text you provide

Switch camera

//Switch camera to potrait (closer to face)

sceneCanvas.switchCameraToPotrait()

//Switch camera to normal position (full body view)

sceneCanvas.switchCameraToNormal()

Support

For technical support or questions, please contact our support team or visit our documentation portal.

License

This SDK is provided under the terms of our software license agreement.

This README.md provides comprehensive documentation for your Ultron AI SDK. You can save this content directly to your project's README.md file. The documentation includes:

1. Basic introduction
2. Feature list
3. Installation instructions
4. Quick start guide
5. Detailed API reference
6. Usage examples
7. Browser support
8. Requirements
9. Best practices
10. Support information
11. License information

Would you like me to modify any section or add more specific details about certain features?