Authentication

Requests to the API carry a credential in an HTTP header. The upload and run endpoints need it on every request. A realtime session sends it once, on the handshake that opens the WebSocket.

Credentials

Send exactly one credential per request.

API keys

1. Sign in to the Hume Platform, or create an account.
2. On the API keys page, select Create API key.
3. Name the key for whatever will use it, and choose its permissions and when it expires.
4. Create the key and copy it. The key is shown only once.

HTTP requests

Set the credential header on every request to an upload or run endpoint. The request below lists your organization’s runs.

curl https://api.cloud.hume.ai/v1/expression/run \
  -H "X-Hume-Api-Key: $HUME_API_KEY"

The SDKs send the key you pass to the client in this header on every request and connection. If you pass none, they read it from the HUME_API_KEY environment variable.

A missing, invalid, or expired credential is rejected with 401 Unauthorized before the request reaches the service. The body has a message, plus a request_id when an API key was rejected, but no type or code. See HTTP errors.

{
  "message": "Unauthorized",
  "request_id": "5c0e2a7d9b4f41e3a8d6c1f07b2e9a44"
}

WebSocket handshake

Set the credential header when opening the connection. The handshake request your client library sends looks like this:

GET /v1/expression/audio/realtime HTTP/1.1
Host: api.cloud.hume.ai
Upgrade: websocket
Connection: Upgrade
X-Hume-Api-Key: <your API key>

A valid credential completes the upgrade, and the server immediately sends session.created. A missing, invalid, or expired credential is rejected with 401 Unauthorized, and a handshake from an organization that is not permitted to use the endpoint is rejected with 403 Forbidden. Both happen before any WebSocket exists, so there is no error message; read the status from your client library’s handshake result.

Browsers

An API key must never ship in client-side code, so call the API from a server you control. To use the API from a web page, relay through that server: the browser sends media to your server, which forwards it to Hume with the credential attached and returns the results. The realtime endpoints need this relay in any case, because browsers cannot set custom headers on a WebSocket handshake.

Next steps