Emotion Cloud API Documentation Ver. 0.0.1 - 2/17/2022

Getting Started

Welcome

EMOTION CLOUD API

Emoshape Emotion Processing Unit can synthesize emotional levels for AI in real-time with responses to one of twelve primary emotions: anger, fear, sadness, disgust, indifference, regret ,surprise, anticipation, trust, confidence, desire and joy, using psychometric functions that shape and react without use of pre-programmed sets of inputs. EPU III is the industry’s first emotion synthesis engine. It delivers high-performance machine emotion awareness, the EPU III family of eMCU are transforming the capabilities of Robots and AI. EmoSHAPE has completed the production of the first EPU (emotional processing unit); a patent pending technology which creates a synthesised emotional response in machines.

Benefits

  • EPU Cloud Service. provides an evaluation platform for the Emotion synthesis. The cloud API is a vehicle to test and evaluate the emotion synthesis functionality of the EPU. The cloud API gives developers immediate access to Cloud advanced emotion processing engine directly from the web, while allowing them to develop proprietary capabilities that provide true differentiation.
  • - The Cloud Service allows users to access all web app and cloud api services. They can input the secret and send text for synthetization in web app for simple test or demo. -
    Steps:
    Input the cloud secret in order to activate the cloud EPU - Send text for text to speech synthetization using Microsoft Azure Speech service with and without Speech Synthesis Markup Language (SSML). The SSML parameters are driven by the EPU Cloud. - Request MDAD buffer with emotions generated from the send text - Enable some options in the Cloud: auto push, auto off, append, words per minute. Additionally, another server is able to extract directly from wav files emotions values.
  • Emoshape delivers the entire BSP and software stack. With a complete suite of development, code sample, EPG machine learning cloud computing, and profiling tools, Emoshape gives you the ideal solution for helping shape the future of Emotion AI and the metaverse with emotional awareness.

License

The cloud API are for personal and commercial projects. Limitations on Transfer and resell of data: Your limited license does not allow to transfer or resell any data from the Emotion processing Unit buffer for example, but not exclusively in a client server configuration.

Speech Emotion Recognition - SER

    Upload wav file

      audio file
    Upload a wav mono file to be recognized. The session duration is limited by the number of EPU instances assigned to your secret expressed in number of hours. Every 24 hours the session duration is reset. The remaining time is updated after each request and it is shown in the upper right corner of the page.

    SER Results

      SER results

  • Cloud Api

  • your Secret Key generate for you in your EPU Cloud account.

  • The secret must be HTML encoded in order to be part of a valid URL, i.e. chars like & or < must be encoded using for example: https://codebeautify.org/html-encode-string
  • In order to extract emotion values from a given wav mono file use: 
            curl -F fileToUpload=@<wav file> https://ser.emohuman.com/api?secret=<your secret>
    The reply is a JSON object with estimated emotion values and the remaining audio time (hh:mm:ss): 
              {"Anger":68,"Disgust":58,"Fear":53,"Joy":22,"Sadness":53,"activation(calm vs. excited)":5.5322,"dominance(passive vs. aggressive)":7.3982,"remaining_time":"1:58:04","valence(positive vs. negative)":-0.8319}
    Optionally an EPU ID can be specified: 
              curl -F fileToUpload=@<wav file> https://ser.emohuman.com/api?secret=<your secret>&epuid=<your EPU ID>
    In this case the reply is the same JSON object as above with an additional epuid field.

    • Emotion Synthesis

      Cloud API initialisation

      Login

      Before making any request to the cloud API, the user must login using the secret key. 
              curl -X POST -H "Content-Type: application/json" -d '{"type":"cloud","secret":"<your secret>"}' https://emohuman.com/login
      If successful, the reply is a JSON object containing the reserved instance EPU ID: 
              {"epuid":"21062304000000ae31001db141c8bcb3","reply":"ok"}
      All other requests must include both the secret and the EPU ID.
      Once reserved, an EPU instance must be periodically updated every 10 seconds using a heartbeat request: 
              curl -X PUT -H "Content-Type: application/json" -d '{"epuid":"<your EPU ID>","secret":"<your secret>"}' https://emohuman.com/heartbeat
      Without the periodic update the reserved EPU instance will be released automatically after 30 seconds after the last request.
      A reserved EPU instance can be released explicitly using a logout request: 
              curl -X PUT -H "Content-Type: application/json" -d '{"epuid":"<your EPU ID>","secret":"<your secret>"}' https://emohuman.com/logout

      All reserved EPU instances for a given secret can be released explicitly using a logout_all request: 
              curl -X PUT -H "Content-Type: application/json" -d '{"secret":"<your secret>"}' https://emohuman.com/logout_all

      MDAD - ESML JSON

      • Sending text for synthetization can be done from command line with the following command: 
        			curl -X POST -H "Content-Type: application/json" -d '{"secret":<your secret>, "epuid":<EPU ID>, "message":"I like you a lot"}' https://www.emohuman.com/send_text
        The reply is a JSON object 
        			{"epuid":"21062304000000ae31001db141c8bcb3","reply":"ok"}
      • After the text is send, the generated MDAD buffer can be obtained with a GET request
        			curl -X GET https://www.emohuman.com/request_buffer?secret=<your secret>&epuid=<EPU ID>
        The JSON reply contains the emotions vector attached to each word:
        			{"emotions":[{"value":"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0","word":"I"},{"value":"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0","word":"like"},{"value":"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0","word":"you"},{"value":"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0","word":"a"},{"value":"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0","word":"lot"},{"value":"0,0,22,0,0,0,0,0,0,0,0,0,5,0,1,0","word":"lot"},{"value":"0,0,33,0,0,0,0,0,0,0,0,0,8,0,2,0","word":"lot"},{"value":"0,0,40,0,0,0,0,0,0,0,0,0,10,0,3,0","word":"lot"},{"value":"0,0,43,0,0,0,0,0,0,0,0,0,10,0,3,0","word":"lot"},{"value":"0,0,45,0,0,0,0,0,0,0,0,0,11,0,3,0","word":"lot"},{"value":"0,0,44,0,0,0,0,0,0,0,0,0,11,0,3,0","word":"lot"},{"value":"0,0,42,0,0,0,0,0,0,0,0,0,10,0,3,0","word":"lot"},{"value":"0,0,38,0,0,0,0,0,0,0,0,0,9,0,3,0","word":"lot"},{"value":"0,0,34,0,0,0,0,0,0,0,0,0,8,0,2,0","word":"lot"},{"value":"0,0,29,0,0,0,0,0,0,0,0,0,7,0,2,0","word":"lot"},{"value":"0,0,24,0,0,0,0,0,0,0,0,0,6,0,2,0","word":"lot"},{"value":"0,0,19,0,0,0,0,0,0,0,0,0,4,0,1,0","word":"lot"},{"value":"0,0,15,0,0,0,0,0,0,0,0,0,3,0,1,0","word":"lot"},{"value":"0,0,11,0,0,0,0,0,0,0,0,0,2,0,0,0","word":"lot"},{"value":"0,0,7,0,0,0,0,0,0,0,0,0,1,0,0,0","word":"lot"},{"value":"0,0,5,0,0,0,0,0,0,0,0,0,1,0,0,0","word":"lot"},{"value":"0,0,3,0,0,0,0,0,0,0,0,0,0,0,0,0","word":"lot"},{"value":"0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0","word":"lot"},{"value":"0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0","word":"lot"},{"value":"0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0","word":"lot"}],"epuid":"210623040000004fcf001d4baeadec69"}
        The emotions vector contains 16 integer values, representing a different emotion intensity, in the following order: "excite", "sure", "happy", "trust", "desire", "fear", "surprise", "inattention", "sad", "nostalgia", "disgust", "anger", "satisfaction", "frustration", "pleasure", "pain".

      SDK Configuration

      • Enable/disable auto push 
                  curl -X PUT -H "Content-Type: application/json" -d '{"secret":<your secret>, "epuid":<EPU ID>, "on": <true or false>}' https://www.emohuman.com/auto_push
        If successful the reply is a JSON object: 
                  {"reply":"ok", "epuid": <EPU ID>}
        otherwise the reply is: 
                  {"reply":"error", "message": <error message>}
      • Enable/disable auto off 
                  curl -X PUT -H "Content-Type: application/json" -d '{"secret":<your secret>, "epuid":<EPU ID>, "on": <true or false>}' https://www.emohuman.com/auto_off
      • Enable/disable append 
                  curl -X PUT -H "Content-Type: application/json" -d '{"secret":<your secret>, "epuid":<EPU ID>, "on": <true or false>}' https://www.emohuman.com/append
      • Change words / min 
                  curl -X PUT -H "Content-Type: application/json" -d '{"secret":<your secret>, "epuid":<EPU ID>, "value": <integer between 0 and 255>}' https://www.emohuman.com/words_per_min
      • Get current configuration 
                  curl -X GET -H "Content-Type: application/json" -d '{"secret":<your secret>}' https://www.emohuman.com/get_config
        If successful returns an JSON object with the current configuration: 
                    {"append":<true or false>, "autoPush": <true or false>, "autoOff": <true or false>, "wordsPerMin": <integer between 0 and 255>}

      Send custom wave

      •           curl -X PUT -H "Content-Type: application/json" -d '{"secret":<your secret>, "epuid":<EPU ID>, "type": <string from the set ["Excite", "Sure", "Happy", "Trust", "Desire", "Fear",
          "Surprise", "Inattention", "Sad", "Nostalgia", "Disgust", "Anger"]>,
        "level": <integer between 0 and 100>, "duration": <integer between 0 and 100>, "origin": <integer between 0 and 65535>, "apex": <integer between 0 and 99>, "curve": <integer between 1 and 255>}' https://www.emohuman.com/custom_wave?secret=<your secret>
        If successful the reply is a JSON object: 
                  {"reply":"ok", "epuid": <EPU ID>}
        otherwise the reply is: 
                  {"reply":"error", "message": <error message>}

      Emotion Generation Control

      • Pause 
                  curl -X PUT -H "Content-Type: application/json" -d '{"epuid":<EPU ID>}' https://www.emohuman.com/pause?secret=<your secret>
      • Resume 
                  curl -X PUT -H "Content-Type: application/json" -d '{"epuid":<EPU ID>}' https://www.emohuman.com/resume?secret=<your secret>
      • Reset 
                  curl -X PUT -H "Content-Type: application/json" -d '{"epuid":<EPU ID>}' https://www.emohuman.com/soft_reset?secret=<your secret>

    Emotional Voice Generation E-TTS

    Web App

        EPU Cloud
      • From the main page text can be send for text to speech synthetization. Two wav files are generated: one that contains the default synthetization and another that contains an enhanced synthesized version using SSML and emotion parameters generated by EPU Cloud. The file name format contains the current date and time and the enhanced wav file name contains ‘_markup’ as suffix. The generated files are listed in the main page, the most recent files first, and can be downloaded.

      • Cloud Api

        The wav files are generated by sending from command line: 
                curl -X POST -H "Content-Type: application/json" -d '{"message":"I like you a lot"}' https://www.emohuman.com/send_text

    Receive events with SocketIO

    The socketIO server has the same address as the HTTP server: https://www.emohuman.com

    MDAD event

    The MDAD event is emitted when a new MDAD matrix is available (every 200 ms). The MDAD matrix is a 10x12 matrix of integers.
    The event is emitted into '/<EPU ID>' namespace for a given EPU instance. The MDAD matrix is send into a JSON object with the following format: 
        {‘epuid’: ‘<EPU ID>’, ‘mdad’: <list of integers of size 10 x 12, first 12 are the first column>}

    TTS event

    The TTS event is emitted when the TTS synthesis is started or stopped. The event is emitted into '/' namespace and contains a JSON object with the following format: 
          {‘epuid’: ‘’, 'started': <true or false>}

This documentation is provided by Emoshape Inc.

© Copyright Emoshape Inc. All Rights Reserved.