What is a Task?

A Task is the response object returned by Hive's API after you submit a request for processing. It contains all relevant details about your submission, including its unique identifier, associated metadata, and current status. Tasks enable you to track and manage your requests, whether they involve detecting objects, moderating content, generating results, or other operations supported by the API.

The Task Object includes the following properties:

Property	Type	Description
id	string	Unique identifier for the task.
project_id	int	The unique ID for the project.
user_id	int	The unique ID for your user account (only returned for sync API).
callback	string	User-provided callback URL when the API request was made.
metadata	string	User-provided metadata when the API request was made.
status	object	Contains the API results for a completed task.
created_on	string	Timestamp of when task was created.

Once you submit content to the API, the response will include a Task Object for you to reference. For async requests, you can use the id to check the status or retrieve the results later. For further details on submission and handling, visit our Sync API Examples or Async API Examples.

Choosing Between Sync or Async API

Hive supports both synchronous and asynchronous API interface protocols.

If you need help determining which submission process best fits your use case, our technical team is happy to help! Just reach out to us at support@thehive.ai.

As a general guideline:

Synchronous API (sync)

https://api.thehive.ai/api/v2/task/sync

Asynchronous API (async)

https://api.thehive.ai/api/v2/task/async

A synchronous endpoint is preferred for users who have real-time needs, low latency requirements, and are submitting continuous / cyclical requests.

The synchronous endpoint keeps the HTTP request open until results have finished processing and then sends the results directly in the response message.

Appropriate for Model Only projects.

The asynchronous endpoint is preferred for users who are submitting their volume in large batches users submitting tasks containing large files (i.e. longer videos or audio clips).

The asynchronous endpoint immediately sends a response acknowledging receipt of the task, along with a unique ‘task_id’. It then closes the connection. Once the task is completed, Hive will send a POST request to the provided callback_url containing the completed task’s results.

Appropriate for both Model Only and Model + Manual Review projects.

Media Types and Data Fields for API Endpoints

Hive offers separate endpoints for different use cases and media types. Submitting the wrong type of file or using an incorrect data field will result in an error from our API. Below are the valid fields and acceptable media formats for each API Endpoint Type. Click here to see the list of acceptable file formats for each media type.

API Endpoint Type	Valid API Form Fields	Accepted Media Type
Visual Moderation	media, url	video, image, gif
Text Moderation	text_data	string
Speech Transcription/Moderation	media, url	video, audio
OCR Moderation	media, url	video, image, gif
Logo Detection	media, url	video, image, gif
Contextual Scene Classification	media, url	video, image, gif
Face Detection + Classification	media, url	video, image, gif

Note on uploading via URLs:
When fetching media submitted from HTTP/HTTPS URLs, the request may fail if the specified host denies the request (e.g. due to request throttling or DOS prevention) or takes too long to respond. To ensure that your request succeeds, you should not depend on externally-hosted media for mission critical applications.