Submitting via Task API

Submitting a Task via API (Sync vs Async)

Hive supports both synchronous and asynchronous API interface protocols.

Our technical team is happy to help you determine the submission process that best fits your use case.

As a general guideline:

Synchronous API (sync)	Asynchronous API (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.

Synchronous API (sync)

Asynchronous API (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.