Authentication

Requests to the API carry an API key in the X-Hume-Api-Key header. The upload and run endpoints need it on every request. A realtime session sends it once, on the handshake that opens the WebSocket.

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 X-Hume-Api-Key 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 key is rejected with 401 Unauthorized before the request reaches the service. The body has a message, plus a request_id when a key was sent and rejected, but no type or code. See HTTP errors.

{
  "message": "Invalid or expired API key. Use a key created in the Hume Platform; keys from app.hume.ai do not work here. See https://dev.hume.ai/expression-measurement/docs/authentication#api-keys",
  "request_id": "5c0e2a7d9b4f41e3a8d6c1f07b2e9a44"
}

WebSocket handshake

Set the X-Hume-Api-Key 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 key completes the upgrade, and the server immediately sends session.created. A missing, invalid or expired key 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 key 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