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.

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.