Items and Characteristics endpoints
Last updated
Was this helpful?
Last updated
Was this helpful?
The Items & Characteristics endpoints surface the items and characteristics detected in an image or video, including sound and speech. Each item or characteristic has a prevalence score which represents the extent to which it is present in a given piece of content. Unitary can also analyse the text that is shared alongside the image or video.
You can use these scores in mappings or models to implement safety policies, for example setting a numerical threshold for automated flagging of content or in a linear regression model (read more in the ).
Unitary output's over 50 different classes you can find onList of Item and Characteristics
Please follow the API Authentication instructions first in order to authenticate with the API. This will generate a token that is valid for 24 hours and must be used in subsequent API requests.
Depending on your use case, pick an image or a video and then use one of the following POST endpoints to send your first request.
Content supplied as a binary file upload:
Content supplied as a resource URL:
Using the GET endpoint may be inadequate for large scale! The recommendation is using the "callback_url" parameter instead. Please check the Integrating Webhooks guide for more information.
Depending on the processing status of the job at the time of request, you can get any of the following as the response from the GET endpoints:
Please follow our thresholding guide: How to select thresholds
(optional but encouraged)
In order to have a scalable end-to-end integration, the last step is to set up the receiving of webhooks as described in the following guide: Integrating Webhooks
This endpoint returns the results of a previously queued classify job.
The response for each item is a prevalence score between 0 and 1 that represents how present it is in the content. 1 is highest prevalence and 0 is lowest prevalence.
You can use these scores in mappings or models to implement safety policies, for example setting a numerical threshold for automated flagging of content or in a linear regression model.
Note that the score meaning and distribution is different for each item: for example, a 0.7 for pepe won't translate to the same likelihood of harmful content as a 0.7 for confederate flag.
Therefore you should calculate an individual threshold for each item. For best performance, we suggest calculating a threshold using labelled data, optimising for the balance of precision and
recall best suited to your needs. The Unitary team is happy to provide guidance on this process.
This endpoint returns the results of a previously queued classify job.
The response for each item is a prevalence score between 0 and 1 that represents how present it is in the content. 1 is highest prevalence and 0 is lowest prevalence.
You can use these scores in mappings or models to implement safety policies, for example setting a numerical threshold for automated flagging of content or in a linear regression model.
Note that the score meaning and distribution is different for each item: for example, a 0.7 for pepe won't translate to the same likelihood of harmful content as a 0.7 for confederate flag.
Therefore you should calculate an individual threshold for each item. For best performance, we suggest calculating a threshold using labelled data, optimising for the balance of precision and
recall best suited to your needs. The Unitary team is happy to provide guidance on this process.
This endpoint queues a job that predicts the Items & Characteristics categories of a single image.
The request must contain either a file (a multi-part form encoded image file) or a url form field (a string containing a URL to download the image file from).
Example CURL:
curl --location --request POST https://api.unitary.ai/v1/classify/items-characteristics/image --header "Authorization: Bearer {API_TOKEN}" --header "Content-Type: multipart/form-data" --form "url={RESOURCE_URL}"
A job ID will be returned in the response.
If a callback_url form field is included in the request then the results webhook will be sent as a POST request to this URL once the image has been classified.
Alternatively results can be obtained by making a GET request to the results endpoint using the job ID.
Webhooks should be implemented for any use of this endpoint at scale to prevent unnecessary polling of the results endpoint.
This endpoint queues a job that predicts the Items & Characteristics categories of a single video.
The request must contain either a file (a multi-part form encoded video file) or a url form field (a string containing a URL to download the video file from).
Example CURL:
curl --location --request POST https://api.unitary.ai/v1/classify/items-characteristics/video --header "Authorization: Bearer {API_TOKEN}" --header "Content-Type: multipart/form-data" --form "url={RESOURCE_URL}"
A job ID will be returned in the response.
If a callback_url form field is included in the request then the results webhook will be sent as a POST request to this URL once the image has been classified.
Alternatively results can be obtained by making a GET request to the results endpoint using the job ID.
Webhooks should be implemented for any use of this endpoint at scale to prevent unnecessary polling of the results endpoint.