Offline ASR API Usage

Using the API¶

Creating an API token¶

The first step to use the API is to create an access token from the web UI. To do that, the user must login and go to "Settings".

Then, select "Add a new API token" and fill the name and scope fields with the desired values.

It's important to remark that once created, the token won't be visible anymore, so it must be saved. However, it can be regenerated later on or deleted.

API headers¶

API can be accessed on: /api/public/v1/ . A link is provided in the bottom left corner of the website.

The access token must be provided as Bearer in the Authorization headers:

import requests

session = requests.Session()
session.headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer 123456",
}

API endpoints¶

To know parameters and the returned objects, please check each API endpoint swagger documentation.

uploads endpoint¶

The start point of the API is the uploads endpoint. This endpoint will allow the user to upload media files for transcription and track their status.

Example of ingest code¶

This example in Python uses requests and requests_toolbelt for an ingest.

import requests
from requests_toolbelt import MultipartEncoder

api_path = "/api/public/v1/uploads/ingest/"
url = f"{service_endpoint}{api_path}"

encoder = MultipartEncoder(
  fields={
    "title": data["title"],
    "language": data["language"],
    "notificationMethod": "CALLBACK",
    "username": data["username"],
    "notificationUrl": data["notificationUrl"],
    "readGroups": data["readGroups"],
    "readUsers": data["readUsers"],
    "transcriptionIsPublic": str(data["transcriptionIsPublic"]),
    "comments": data["comments"],
    "mediaFile": (
      file_name,
      open(video_path, "rb"),
      "application/octet-stream",
    ),
  }
)

response = session.post(
  url,
  headers={"Content-Type": encoder.content_type},
  data=encoder
)

media-files-endpoint¶

When the files are already uploaded and transcribed, this endpoint will return their details.

editor endpoint¶

When the files are already uploaded and transcribed, the links to the editor will be available.

API notifications and callbacks¶

There are several situations when the application will send notifcations using the provided callback URL during the ingest or emails.

• When an ingest is finished (finished)
• When the ingest was not completed because it was already sent (already-exists)
• When a transcription has been updated (captions-updated)
• When an error happened during the process (error)

Please, refer to the ingest API documentation for more information.

Example of callback handling¶

The following example uses Flask route syntax.

@app.route("/ttaas-callbacks", methods=['POST'])
def ttaas_callbacks():
    # Getting the parameters from the form
    callback_type = request.form["callback_type"]
    # Passed as ?extra_field=12345 in the callback URL
    extra_field = request.form["extra_field"]
    media_id = request.form["mediaId"]

    if callback_type == "ALREADY_EXISTS":
        state = request.form["state"]
        # The media ID that already exists
        media_id = request.form["existingMediaId"]
        if state == "COMPLETED":
          # Handle already-exists with completed status
        else:
            # Handle already-exists with not completed status

    if callback_type == "FINISHED":
        # Handle finished callback

    if callback_type == "ERROR":
        # Handle error callback

    if callback_type == "CAPTION_UPDATED":
        # Handle error callback

    # Must return a code 200
    return "", 200

Upload states¶

Transcription request (Ingest)¶

Translation request (update)¶