⚠️

Heads up: This documentation is for Scribe v1. For the latest version of Scribe please refer to the v2 documentation.

Batch API development

Scribe contains two apis: A Batch REST API that asynchronously processes audio / video files, and a websocket API that transcribes uncompressed audio in real time. To get started we will use the REST API. For to get up and running with the websocket API, visit our real time streaming guide.

Full documentation for the Batch API can be found in our Batch API (OpenAPI Specification) page. Those pages include information on the types of audio / video files we currently support as well as how you can retrieve alternate transcription formats like WebVTT (opens in a new tab).

In order to interact with the Scribe API, you need an authentication token. To get an authentication token, visit our authentication guides.

The batch API provides a polling mechanism, where users can upload a file and query for results. Here is example Python code to do so:

import requests
import time
 
 
url = 'https://scribe.kensho.com/api/v1/transcription'
token = '<YOUR TOKEN HERE>'
 
def make_polling_request(data):
    """Make a polling request to the server"""
    authorization = "Bearer " + token
    response = requests.post(
        url,
        data=data,
        headers={'Content-Type': 'application/mp3', 'Authorization': authorization}
    )
    unique_id = response.json()['unique_id']
    print('Started transcription with data', data, 'unique id', unique_id)
 
    while True:
        response = requests.get(
            url + '?unique_id=' + unique_id,
            headers={'Authorization': authorization}
        )
        result = response.json()
        print(result)
 
        if result['status'] != 'pending':
            return result
 
        time.sleep(1)

This snippet will upload a file to the server, and then poll until the request either succeeds or fails. To use the snippet:

# Make an example successful request
make_polling_request(b'_mock_pipeline_success_')
 
print("\n")
 
# Make an example request that fails audio transcription
make_polling_request(b'_mock_fail_transcription_')
 
print("\n")
 
# Upload a real MP3 file
with open("/path/to/your/file.mp3", "rb") as f:
    audio_content = f.read()
 
make_polling_request(audio_content)

To include TranscriptionOptions such as hotwords along with your file, you must make a POST request using HTTP multipart form encoding

Example python code for a multipart form POST

import requests
import time
 
 
url = 'https://scribe.kensho.com/api/v1/transcription'
token = '<YOUR TOKEN HERE>'
 
def make_polling_request():
    """Make a polling request to the server"""
    authorization = "Bearer " + token
    transcription_options = {'TranscriptionOptions': '{"hotwords": ["port"]}'}
 
    # File should be a list of tuples where the first is "file" and the second is another tuple
    # which takes the form (file_name, file_pointer opened in 'rb' mode, file_mime_type)
    file =[('file', ('file.mp3', open("/path/to/your/file.mp3", "rb"), 'application/mp3'))]
 
 
    response = requests.post(
        url,
        data=transcription_options,
        files=file,
        headers={'Authorization': authorization}
    )
 
    unique_id = response.json()['unique_id']
    print('Started transcription with data', file, 'unique id', unique_id)
 
    while True:
        response = requests.get(
            url + '?unique_id=' + unique_id,
            headers={'Authorization': authorization}
        )
        result = response.json()
        print(result)
 
        if result['status'] != 'pending':
            return result
 
        time.sleep(1)