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.
- Retrieving JSON and Zip CSV job results are now their own endpoints
- Support for uploading locally hosted files
- A webhook to be notified of a job's completion
- Our models now support additional configurations
- Transcription is now optional and its configuration is now shared across models
- Expanded options for granularity when using our Language model
- Speech prosody outputs are now configurable via a sliding window or granularity
- 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
orartifacts_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 JSONGET /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 tonull
- You still have your choice of the same 20+ languages we support via the
language
field on thetranscription
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
- Support for language granularity in the
HumeStreamClient
- Support for named entity recognition in the
HumeBatchClient
- Support for error codes
- Improved type hints for
StreamSocket
- Support for new streaming connection parameters
- Resize the streaming context window with
stream_window_ms
- Reset streaming connection context with
reset_stream
- Get job details with
get_job_details
- Resize the streaming context window with