Learn how to define your Task, then send it
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 [email protected].
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.