To call the Streaming API from your own WebSockets client you'll need the API endpoint, a JSON message, and an API key header/param.

More information can be found in the Streaming API reference.

To get started, you can use a WebSocket client of your choice to connect to the models endpoint:

wss://api.hume.ai/v0/stream/models

Make sure you configure the socket connection headers with your personal API key

X-Hume-Api-Key: <YOUR-API-KEY>

📘
The default WebSockets implementation in your browser may not have support for headers. If that's the case you can set the apiKey query parameter.

And finally, send the following JSON message on the socket:

{
    "models": {
        "language": {}
    },
    "raw_text": true,
    "data": "Mary had a little lamb"
}

You should receive a JSON response that looks something like this:

{
  "language": {
    "predictions": [
      {
        "text": "Mary",
        "position": { "begin": 0, "end": 4 },
        "emotions": [
          { "name": "Anger", "score": 0.012025930918753147 },
          { "name": "Joy", "score": 0.056471485644578934 },
          { "name": "Sadness", "score": 0.031556881964206696 },
        ]
      },
      {
        "text": "had",
        "position": { "begin": 5, "end": 8 },
        "emotions": [
          { "name": "Anger", "score": 0.0016927534015849233 },
          { "name": "Joy", "score": 0.02388327568769455 },
          { "name": "Sadness", "score": 0.018137391656637192 },
          ...
        ]
      },
      ...
    ]
  }
}

Sending Images or Audio

The Streaming API requires that you base64 encode your media before sending it over a WebSocket connection.

Data Encoding

Here's a quick example of encoding data in Python:

import base64
from pathlib import Path

def encode_data(filepath: Path) -> str:
    with Path(filepath).open('rb') as fp:
        bytes_data = base64.b64encode(fp.read())
        encoded_data = bytes_data.decode("utf-8")
        return encoded_data

filepath = "<path-to-your-media>"
encoded_data = encode_data(filepath)
print(encoded_data)

You can also use an online converter to do this step.