Asynchronous features require long running processes to analyze input data.

You can recognize a feature being asynchronous if it has the 3 following endpoints:

• Launch Job
• Get Job Results
• List Jobs

Examples of asynchronous features include: Speech to Text, OCR Tables and Videos Analysis.

Asynchronous Process

Asynchronous features require a two steps process:

• Initial Call: Making a request just like for any other features, except that it creates an Asynchronous Job in the Background and returns the Job ID.
• Polling Job: You can use the previously returned Job ID to get info on the current status of the job, or get the result of analysis if the job is finished. The Job Can be in one of the three following states:
  • processing: The analysis is not finished and we need to wait longer
  • failed: An error occurred and an error message will be returned in the response
  • finished: The job is finished and the result is returned in the response

An optional endpoint also allows you to list all the job you launched for a certain feature.

📘

You can use Webhooks too!

You can pass a webhook_receiverparameter to the Launch job request and you will receive a POST request to your endpoint containing the Job result as soon as it finishes. No Need to pull the Job status every 5 seconds.

Quick Example

Here is an example using Speech To Text with Python

First we Launch the job:

import requests


url = "https://api.edenai.run/v2/audio/speech_to_text_async"

files = {"file": ("audio.wav", open("audio.wav", "rb"), "audio/x-wav")}
payload = {
    "providers": "amazon",
    "language": "en"
    "speakers": "2",
    "profanity_filter": "false",
    "webhook_receiver": "http://my-webhook-receiver-enpoint.com/
}
headers = {
    "accept": "application/json",
    "authorization": "Bearer <API_KEY>"
}

response = requests.post(url, data=payload, files=files, headers=headers)
data = response.json()

print(data)  # {"public_id": "9421ae03-6180-4aef-82ce-19b2c33e9397"}

We can see that the job as been launched an an ID has been returned.

Since I passed a webhook_receiver I could just wait until I receive a POST request on the receiver to retrieve the result, but let's get the job status for sake of demonstration:

import requests

# url including the job id
url = "https://api.edenai.run/v2/audio/speech_to_text_async/9421ae03-6180-4aef-82ce-19b2c33e9397"

headers = {
    "accept": "application/json",
    "authorization": "Bearer <API_KEY>"
}

response = requests.get(url, headers=headers)
data = response.json()
print(data['status'])  # processing | finished | failed