Batch API Tutorial


We saw in the Get Started guide the basics of how to use the Batch API to process the facial expressions in a single image. Here we'll go deeper into uploading your own files and running Hume models on larger batches of data.

If you haven't already, grab your API key using the instructions in the Get Started guide.

Uploading your data

To process a folder of your own data with the Batch API, you can upload them to a cloud storage location or upload your local file.

Example data

We'll use a collection of license-free images which contain expressive faces. You can download the zip file here if you want to check out individual images.

Face Images

Calling the Batch API

Calling the Batch API with a zipped folder will look almost identical to the command for a single file, swap out the URL and the Batch API will handle the decompression.

curl \
  --header "Content-Type: application/json" \
  --header "X-Hume-Api-Key: <YOUR-API-KEY>" \
  --data '{
    "models": {
      "face": {}
    "urls": [
from hume import HumeBatchClient
from hume.models.config import FaceConfig

client = HumeBatchClient("<your-api-key>")
urls = [""]
config = FaceConfig()
job = client.submit_job(urls, [config])


details = job.await_complete()
print("Predictions downloaded to predictions.json")

To do the same with a local file:

curl \
  --header "Content-Type: multipart/form-data" \
  --header "X-Hume-Api-Key: <YOUR-API-KEY>" \
  --form json='{
    "models": {
      "face": {}
  --form [email protected]
  --form [email protected]

What’s Next

Make your first Hume API Request or learn more about using the Batch API