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 \
>     --request POST \
>     --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 \
>     --request POST \
>     --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"
Built with