Get Started with Hume's APIs

Getting your API key

  1. Sign in to Hume
  2. Navigate to the API Keys page
  3. Copy your API key
API Key

API Key

📘

Your API key is a random sequence of letters and numbers.

It should look something like ntylOFypHLRXMmjlTxljoecAnMgB30JtOLZC2nph1TYErCvv

Your first API call

Let's start by trying out the facial expression model.
We'll use this picture of our friend, David Hume.

David Hume

David Hume

Starting a job

To run a job with the Hume Batch API, open a terminal window and run the following curl command: (make sure to replace with the actual API key you got in the steps above.

curl https://api.hume.ai/v0/batch/jobs
--request POST  
--header "Content-Type: application/json"  
--header "X-Hume-Api-Key: <YOUR-API-KEY>"  
--data '{  
    "urls": [  
        "https://iep.utm.edu/wp-content/media/hume-bust.jpg"  
    ],  
    "models": {  
        "face": {}  
    }  
}'

# Response
{
    "job_id": "6b5e7b4f21a247bd8247b91983f12d57"
}
from hume import HumeBatchClient
from hume.models.config import FaceConfig

client = HumeBatchClient("<YOUR-API-KEY>")
urls = ["https://iep.utm.edu/wp-content/media/hume-bust.jpg"]
config = FaceConfig()
job = client.submit_job(urls, [config])

Checking job status

Check the status of your job with another command: (replace both <YOUR-API-KEY> and <JOB-ID>)

curl --request GET \
     --url https://api.hume.ai/v0/batch/jobs/<JOB-ID> \
     --header 'X-Hume-Api-Key: <YOUR-API-KEY>' \
     --header 'accept: application/json; charset=utf-8'

# Response
{
    "job_id": "<JOB-ID>",
    "request": {...},
    "state": {
        "status": "COMPLETED",
        ...
    },
    "user_id": "<USER-ID>"
}
status = job.get_status()
print(f"Job status: {status}")

details = job.get_details()
run_time_ms = details.get_run_time_ms()
print(f"Job ran for {run_time_ms} milliseconds")

📘

If your job status is QUEUED or IN_PROGRESS you can wait a few seconds and try the last command again. Processing time will vary based upon the job size and server load.

Your predictions

To retrieve your predictions: (replace both <YOUR-API-KEY> and <JOB-ID>)

curl --request GET \
     --url https://api.hume.ai/v0/batch/jobs/<JOB-ID>/predictions \
     --header 'X-Hume-Api-Key: <YOUR-API-KEY>' \
     --header 'accept: application/json; charset=utf-8'
from pprint import pprint

predictions = job.get_predictions()
pprint(predictions)

The returned Face model predictions include high-dimensional emotion embeddings for the detected facial expression, as well as bounding box coordinates for the detected face within the image.

[
  {
    "source": {
      "type": "url",
      "url": "https://iep.utm.edu/wp-content/media/hume-bust.jpg"
    },
    "results": {
      "predictions": [
        {
          "file": "hume-bust.jpg",
          "file_type": "image",
          "models": {
            "face": {
              "metadata": null,
              "grouped_predictions": [
                {
                  "id": "unknown",
                  "predictions": [
                    {
                      "frame": 0,
                      "time": 0.0,
                      "prob": 0.999954104423523,
                      "box": {
                        "x": 94.04583740234375,
                        "y": 38.42132568359375,
                        "w": 66.237548828125,
                        "h": 86.2457275390625
                      },
                      "emotions": [
                        {
                          "name": "Admiration",
                          "score": 0.16469910740852356
                        },
                        {
                          "name": "Adoration",
                          "score": 0.13865520060062408
                        },
                        // ...more emotion embeddings
                      ],
                      "facs": null,
                      "descriptions": null
                    }
                  ]
                }
              ]
            }
          }
        }
      ],
      "errors": []
    }
  }
]

📘

Each embedding object will include the emotion label (name) and a score. The score is a value between 0 and 1 which indicates the likelihood a person would perceive the expression as the respective emotion label. Within the predictions you can expect scores for each of the emotion labels to be present within the emotions list, as each dimension is predicted non-deterministically by Hume's expression models.