Skip to main content

Training API Overview

The Valossa Training API allows you to create custom face galleries and train the system to recognize specific people in your video analysis jobs.

Base URL​

https://api-eu.valossa.com/training/1.0/

Overview​

By default, Valossa AI uses the Valossa Celebrities Gallery, which contains thousands of known public figures. The Face Training API lets you supplement this with your own custom galleries containing any face identities relevant to your use case.

Trained face identities appear in the similar_to fields of human.face detections in Valossa Core metadata.

Prerequisites​

  • A Valossa AI subscription that includes face-related functionality.
  • Your existing API key (the same key used for video analysis works for face training).

Galleries​

When you start training custom faces without specifying a gallery, a default gallery is created automatically for your account. The default gallery:

  • Is created implicitly on first use
  • Cannot be named
  • Is limited to one per account
  • Is used automatically for video analysis if no gallery is specified in the new_job request

Non-Default Galleries​

You can explicitly create additional non-default galleries for more advanced use cases:

  • Each gallery has a name and a unique UUID
  • You can create multiple non-default galleries
  • Must be explicitly specified in the new_job request to be used

A common use case for multiple galleries is when you serve multiple customers, each needing their own set of face identities. By using separate galleries, Customer A's trained faces will not be applied to Customer B's video analysis jobs.

Workflow​

If you need a non-default gallery, create one first. The API returns the gallery's UUID.

2. Upload Face Images​

Upload one or more images of each person you want the system to recognize. Use the upload_image function in the Training API. The more varied and high-quality images you provide for each person, the better the recognition accuracy.

3. Analyze Videos​

Submit videos for analysis using new_job. Specify which gallery to use:

  • Omit the gallery parameter: The default gallery is used.
  • Specify a gallery UUID: The specified non-default gallery is used.

4. Read Results​

Recognized faces appear in the similar_to array within the a (attributes) field of each human.face detection. Each match includes:

  • name -- The person's name as trained
  • c -- Confidence score (0.0 to 1.0)
  • gallery.id -- UUID of the gallery the match came from
  • gallery_face.id -- UUID of the specific face identity within the gallery
  • gallery_face.name -- Name of the person

API Methods​

The Training API follows the same conventions as Core API:

  • Read operations use HTTP GET
  • Write/delete operations use HTTP POST
  • Responses are JSON
  • HTTP 200 indicates success; non-200 indicates an error with details in the errors array

Endpoints​

FunctionMethodDescription
upload_imagePOSTUpload a face image for training
create_face_galleryPOSTCreate a new non-default face gallery
update_face_galleryPOSTUpdate a non-default gallery name
list_face_galleriesGETList all your face galleries
create_face_identityPOSTCreate a face identity in a gallery
add_face_imagePOSTAttach an uploaded image to a face identity
list_face_identitiesGETList face identities in a gallery
list_face_imagesGETList images assigned to one face identity
update_face_identityPOSTUpdate face identity fields
remove_face_imagePOSTRemove one training image
remove_face_identityPOSTRemove one face identity

Detailed endpoint docs:

Notes​

  • Training custom faces may cause some additional processing time for your video analysis jobs.
  • Gallery management (creating, listing, deleting galleries) and face training (uploading images) can also be done through the Valossa Portal graphical interface.
  • The gallery features and the similar_to_face_id grouping structure were introduced in Valossa Core metadata version 1.3.4. Legacy gallery faces created before this version may not have face IDs (UUIDs) and thus cannot be found in the similar_to_face_id structure.