Custom Models API

Training a custom model

In this guide we will walk you through training your own custom model.

Starting a training job

Here we kick off a training job using a dataset that’s already been registered for you. The resulting model will classify facial expressions as negative, positive, or neutral.

Note that we’ve set target_feature to “Affect”. This refers to the name of the column that we want to predict from our dataset.

cURL
$curl --location https://api.hume.ai/v0/batch/jobs/tl/train \
> --header "X-Hume-Api-Key: $API_KEY" \
> --header 'Content-Type: application/json' \
> --data '{
> "custom_model": {
> "name": "Negative, Neutral, & Positive Facial Expressions",
> "description": "Is Facial Expression Negative, Neutral or Positive"
> },
> "dataset": {
> "id": "ef7955ce-1755-4942-8615-bc16e654e7e5"
> },
> "target_feature": "Affect",
> "task": {
> "type": "classification"
> }
>}'

You’ll get back a job ID that you can use to check the status of your training job.

Response
1{
2 "job_id": "<JOB ID>"
3}

Checking the status of your training job

Using the job ID from the previous step, you can get details about the current status of your training job.

cURL
$curl --location --globoff https://api.hume.ai/v0/batch/jobs/$JOB_ID \
> --header "X-Hume-Api-Key: $API_KEY"

It may take a few minutes for your model to be ready, but once training is complete you will see the status as COMPLETED and you’ll have access to your new model.

Response
1{
2 "type": "TRAINING",
3 "job_id": "<JOB ID>",
4 "user_id": "<USER ID>",
5 "request": {
6 "custom_model": {
7 "name": "Negative, Neutral, & Positive Facial Expressions",
8 "description": "Is Facial Expression Negative, Neutral or Positive",
9 },
10 "dataset": {
11 "id": "ef7955ce-1755-4942-8615-bc16e654e7e5"
12 },
13 "target_feature": "interaction",
14 "task": {
15 "type": "classification"
16 }
17 },
18 "state": {
19 "status": "COMPLETED",
20 "created_timestamp_ms": 42,
21 "started_timestamp_ms": 32,
22 "ended_timestamp_ms": 23,
23 "custom_model": {
24 "id": "<CUSTOM MODEL ID>"
25 }
26 }
27}

Testing your custom model

Your custom model is ready to use!

You can test your model by sending a request to the Custom Models inference endpoint with URLs of images to classify. The model we trained is a facial expression classifier, so test URLs should point to images of faces.

cURL
$curl --location https://api.hume.ai/v0/batch/jobs/tl/inference \
> --header X-Hume-Api-Key: $API_KEY \
> --header 'Content-Type: application/json' \
> --data '{
> "custom_model": {
> "id": "<CUSTOM MODEL ID>"
> },
> "urls": ["<URL TO TEST FILE>"]
> }'

Just like before, we get back a job ID that we can use to check the status of our job.

Response
1{
2 "job_id": "<JOB ID>"
3}

Checking the status of your inference job

Use the job ID from the previous step to check on the status of your model inference job.

cURL
$curl --location --globoff https://api.hume.ai/v0/batch/jobs/$JOB_ID \
> --header "X-Hume-Api-Key: $API_KEY"

Once the model is done predicting the classes of the images you provided, you’ll get a COMPLETED status.

Response
1{
2 "type": "INFERENCE",
3 "job_id": "<JOB ID>",
4 "user_id": "<YOUR USER ID>",
5 "request": {},
6 "state": {
7 "status": "COMPLETED",
8 "created_timestamp_ms": 42
9 }
10}

Getting model predictions

Finally, you can request the actual model predictions from the inference job. The JSON result will show the predicted class for each image you provided.

cURL
$curl --request GET \
> --url https://api.hume.ai/v0/batch/jobs/$JOB_ID/predictions \
> --header "X-Hume-Api-Key: $API_KEY" \
> --header "accept: application/json; charset=utf-8"