Back to All
added

Release May 2023

29 days ago by Chris Gregory

Batch API Update

New Features

The latest release of the batch API comes with many highly requested features.

  1. Retrieving JSON and Zip CSV job results are now their own endpoints
  2. Support for uploading locally hosted files
  3. A webhook to be notified of a job's completion
  4. Our models now support additional configurations
    1. Transcription is now optional and its configuration is now shared across models
    2. Expanded options for granularity when using our Language model
    3. Speech prosody outputs are now configurable via a sliding window or granularity
    4. Support for Hume's anonymized Facial Expression Model / facemesh model providing anonymized facial expression analysis

Migration Guide

This major update comes with a few breaking changes. Since these changes will be available on existing /v0/batch endpoints, code depending on /v0/batch endpoints will need to be updated.

Please follow the sections below for specifics on how to migrate your workloads.

Getting Job Results

  • If you rely on predictions_url or artifacts_url when getting job results you will need to migrate to two new endpoints:
    • GET /v0/batch/jobs/{JOB-ID}/predictions to get predictions as JSON
    • GET /v0/batch/jobs/{JOB-ID}/artifacts to get artifacts including results CSVs
  • If you rely on the errors_url field you can find the same information now in the predictions JSON
curl \
  https://api.hume.ai/v0/batch/jobs/{JOB-ID}/predictions \
  -H X-Hume-Api-Key:{API-KEY}

curl \
  https://api.hume.ai/v0/batch/jobs/{JOB-ID}/artifacts \
  -H X-Hume-Api-Key:{API-KEY}

Start Job Request Format Change

Job requests should now be passed in as multipart/form-data

Example One:

Past Request Format

curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:application/json \
  -H X-Hume-Api-Key:{API-KEY} \
  --data '{
    "models": {
      "face": {}
    },
    "urls": [
      "https://iep.utm.edu/wp-content/media/hume-bust.jpg",
      "https://hume-tutorials.s3.amazonaws.com/faces.zip"
    ]
  }'

Post Release Request Format

# Multipart Request
curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:multipart/form-data \
  -H X-Hume-Api-Key:{API-KEY} \
  --form json='{
    "models": {
      "face": {}
    },
    "urls": [
      "https://iep.utm.edu/wp-content/media/hume-bust.jpg",
      "https://hume-tutorials.s3.amazonaws.com/faces.zip"
    ]
  }'

Example Two:

Past Request Format

curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:application/json \
  -H X-Hume-Api-Key:{API-KEY} \
  --data '{
    "models": {
      "language": {
        "language": "en",
        "granularity": "word"
      }
    },
    "urls": [
      "https://hume-tutorials.s3.amazonaws.com/podcast.mp4"
    ]
  }'

Post Release Request Format

# Multipart Request
curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:multipart/form-data \
  -H X-Hume-Api-Key:{API-KEY} \
  --form json='{
    "models": {
      "language": {
        "granularity": "word"
      }
    },
    "transcription": {
      "language": "en"
    },
    "urls": [
      "https://hume-tutorials.s3.amazonaws.com/podcast.mp4"
    ]
  }'

Jobs with Local Files

  • To start a job you can continue to use POST /v0/batch/jobs
  • If no models are explicitly specified, all models will be run with sensible default parameters
curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:multipart/form-data \
  -H X-Hume-Api-Key:{API-KEY} \
  -F [email protected]{FILE-PATH-1} \
  -F [email protected]{FILE-PATH-2}

Webhook Support

  • When starting a new job, you can now provide a callback URL to be notified when the job is complete
  • On completion, a POST request will be made to the URL with the status of the job and either the generated JSON predictions or the reason for failure
curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:multipart/form-data \
  -H X-Hume-Api-Key:{API-KEY} \ 
  -F [email protected]{FILE-PATH} \
  -F json='{"callback_url": "https://your.webhook.com/api"}'

Opting Out of Audio Transcription

  • Transcription can now be configured separately from our models
  • You can turn off transcription by setting the transcription field on the request object to null
  • You still have your choice of the same 20+ languages we support via the language field on the transcription object
curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:multipart/form-data \
  -H X-Hume-Api-Key:{API-KEY} \
  -F [email protected]{FILE-PATH} \
  -F json='{"transcription": null}'

Emotional Language Model Granularity

  • The choice of granularity options for our Emotional Language model has been expanded
  • You can now choose between generating predictions for each word, sentence, utterance, or conversational turn
  • An utterance corresponds to a natural pause or break in conversation, while a conversational turn corresponds to a change in speaker
curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:multipart/form-data \
  -H X-Hume-Api-Key:{API-KEY} \
  -F [email protected]{FILE-PATH} \
  -F json='{"models": {"language": {"granularity": "conversational_turn"}}}'

Prosody Model Granularity

  • You now have more control over how prosody predictions are generated
  • You can choose to use a sliding window with a configurable length and step size to determine for which time intervals predictions are generated
  • Or, you can choose a granularity (the same choices as the language model) at which to generate predictions
curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:multipart/form-data \
  -H X-Hume-Api-Key:{API-KEY} \
  -F [email protected]{FILE-PATH} \
  -F json='{"models": {"prosody": {"window": {"length": 5, "step": 2}}}}'

curl \
  https://api.hume.ai/v0/batch/jobs \
  -H Content-Type:multipart/form-data \
  -H X-Hume-Api-Key:{API-KEY} \
  -F [email protected]{FILE-PATH} \
  -F json='{"models": {"prosody": {"granularity": "utterance"}}}'

Python SDK Updates