NAV
NodeJS Java Python cURL

Introduction

Welcome to Amberscript's Transcription API

We will provide you with an API_KEY required to access our endpoints.

When you upload a file, our transcribers or automatic speech recognition engines will get to work and create a transcript or subtitles.

Authentication

Language Codes

Language Code
Afrikaans af-za
Albanian sq-al
Amharic am-et
Arabic ar
Armenian hy-am
Azerbaijani az-az
Bahasa Indonesia id-id
Basque eu-es
Bengali (Bangladesh) bn-bd
Bengali (India) bn-in
Bosnian bs-ba
Bulgarian bg
Burmese my-mm
Catalan ca
Chinese (Mandarin) cmn
Croatian hr
Czech cs
Danish da
Dutch nl
English (Australia) en-au
English (United Kingdom) en-uk
English (United States) en-us
English (all accents) en
Estonian et-ee
Farsi (Iran) fa-ir
Filipino fil-ph
Finnish fi
Flemish nl-be
French (Canada) fr-ca
French fr
Galician gl-es
Georgian ka-ge
German (Austria) de-at
German (Switzerland) de-ch
German de
Greek el
Gujarati gu-in
Hebrew iw-il
Hindi hi
Hungarian hu
Icelandic is-is
Italian it
Japanese ja
Javanese jv-id
Kannada kn-in
Khmer km-kh
Korean ko
Lao lo-la
Latvian lv
Lithuanian lt
Macedonian mk-mk
Malay ms
Malayalam ml-in
Marathi mr-in
Mongolian mn-mn
Nepali (Nepal) ne-np
Norwegian no
Polish pl
Portuguese (Brazil) pt-br
Portuguese pt
Punjabi pa-guru-in
Romanian ro
Russian ru
Serbian sr-rs
Sinhala si-lk
Slovakian sk
Slovenian sl
Spanish es
Sundanese su-id
Swahili (Kenya) sw-ke
Swahili (Tanzania) sw-tz
Swedish sv
Tamil (India) ta-in
Tamil (Malaysia) ta-my
Tamil (Singapore) ta-sg
Tamil (Sri Lanka) ta-lk
Telugu te-in
Thai th-th
Turkish tr
Ukrainian uk-ua
Urdu (India) ur-in
Urdu (Pakistan) ur-pk
Uzbek uz-uz
Vietnamese vi-vn
Zulu zu-za

Uploading and status

Uploading A File

HttpResponse<String> response = Unirest.post("https://api.amberscript.com/api/jobs/upload-media?transcriptionType=transcription&jobType=direct&language=nl&apiKey={{YOUR_API_KEY}}")
  .asString();

const request = require('request');
const fs = require('fs');

let options = {
  method: 'POST',
  url: 'https://api.amberscript.com/api/jobs/upload-media',
  qs: {
    apiKey: 'YOUR_API_KEY',
    transcriptionType: 'transcription',
    jobType: 'direct',
    language: 'nl',
    numberOfSpeakers: '2'
  },
  headers: {'content-type': 'multipart/form-data'},
  formData: {file: fs.createReadStream("./path/to/my_file.mp3")}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = 'https://api.amberscript.com/api/jobs/upload-media'
filepath = '/Users/userA/Downloads/my-file.mp3'
querystring = {"jobType":"direct","language":"nl","transcriptionType":"transcription","apiKey":"YOUR_API_KEY"}
files = {'file': open(filepath, 'rb')}

response = requests.post(url, files=files, verify=False, params=querystring)

print(response.status_code)
print(response.text)

curl --request POST --url 'https://api.amberscript.com/api/jobs/upload-media?transcriptionType=transcription&jobType=direct&language=nl&apiKey={{YOUR_API_KEY}}' --form file=@./my-file.mp3

Example: Response to a POST request:

{
  "jobStatus": {
    "jobId": "JOB_ID",
    "created": 82800000,
    "language": "en",
    "notes": null,
    "status": "OPEN",
    "nrAudioSeconds": 45,
    "transcriptionType": "translatedSubtitles",
    "filename": "file_name.mp3",
    "jobType": "perfect",
    "sourceJobId": "SOURCE_JOB_ID", // only present for translated subtitles jobs.
    "targetLanguage": "nl" // OPTIONAL, translatedSubtitles only
  }
}

Upload a file for transcription.

HTTP Request

POST /jobs/upload-media

Query Parameters

Parameter Default Description/Example
language en af-za, sq-al, am-et, ar, hy-am, az-az, id-id, eu-es, bn-bd, bn-in, bs-ba, bg, my-mm, ca, cmn, hr, cs, da, nl, en-au, en-uk, en, et-ee, fa-ir, fil-ph, fi, nl-be, fr-ca, fr, gl-es, ka-ge, de-at, de-ch, de, el, gu-in, iw-il, hi, hu, is-is, it, ja, jv-id, kn-in, km-kh, ko, lo-la, lv, lt, mk-mk, ms, ml-in, mr-in, mn-mn, ne-np, no, pl, pt-br, pt, pa-guru-in, ro, ru, sr-rs, si-lk, sk, sl, es, su-id, sw-ke, sw-tz, sv, ta-in, ta-my, ta-sg, ta-lk, te-in, th-th, tr, uk-ua, ur-in, ur-pk, uz-uz, vi-vn, zu-za, auto
transcriptionType transcription transcription, captions, translatedSubtitles
jobType direct perfect, direct
numberOfSpeakers 2 1, 2, 3, 4, 5
callbackUrl (OPTIONAL) NONE YOUR_CALLBACK_URL
transcriptionStyle (OPTIONAL) cleanread cleanread, verbatim
turnaroundTime (OPTIONAL) FIVE_DAYS - transcription/captions, SEVEN_DAYS - translatedSubtitles Hint: Get in touch if you need a turnaround time other than the default one.
targetLanguage (OPTIONAL) NONE pl, en, ru, fr-ca, ca, zh, ga, hu, pt, da, de-at, fr, nl, en-au, ko, it, de, fi, cmn, ja, de-ch, en-us, ro, pt-br, nl-be, cs, no, sv, en-uk, es
glossaryId (OPTIONAL) NONE YOUR_GLOSSARY_ID

Uploading With callbackUrl

  1. When you make a request with a callbackUrl, we send the final status of your upload to this url.
  2. When processing is complete, this status is sent via a POST request (see below).
  1. Your callbackUrl endpoint should respond with any 2xx if you successfully receive the status.

There are times when our system can encounter issues with your job. When that is the case, the callback will be sent with an ERROR status, and the content of the callback will look like this:

{
  "jobId": "JOB_ID",
  "created": 82800000,
  "language": "nl",
  "status": "ERROR",
  "nrAudioSeconds": 45,
  "transcriptionType": "transcription",
  "filename": "file_name.mp3",
  "jobType": "direct",
  "errorMsg": "No speech found"
}

Otherwise, you will get a callback informing you that your job was successfully transcribed.

{
  "jobId": "JOB_ID",
  "created": 82800000,
  "language": "nl",
  "status": "DONE",
  "nrAudioSeconds": 45,
  "transcriptionType": "captions",
  "filename": "file_name.mp3",
  "jobType": "direct"
}

Uploading Without callbackUrl

  1. When you make a request without the callbackUrl, store the value of the jobId returned upon a successful call ( see Example in right pane).
  2. Use the jobId to periodically check the status of the upload request ( e.g. every 5 mins).

Uploading With glossaryId

When using a glossaryId with your request, you first need to have created a glossary to be used. Read here for more information on how to work with glossaries. You can either:

or

Automatic language identification

You can let the automatic speech recognition engine determine the language of uploaded media automatically. To do so, you need to set the value of language request parameter to auto. - Supported languages: English, Dutch, German, French and Italian

Note: Automatic language predictions can be wrong and manual specification is recommended. If you need support or have an issue, please get in touch with us via info@amberscript.com.

File requirements:

If you need support for a different file format, please get in touch with us: info (at) amberscript (dot) com

Uploading A File by URL

Upload a file from a remote location - for example a file stored on AWS S3. The file has to be publicly accessible from a URL or it has to be presigned download URL.

Please note that this endpoint uses parameters in the body of the request.

HttpResponse<String> response = Unirest.post("https://api.amberscript.com/api/jobs/upload-media-from-url?apiKey={{YOUR_API_KEY}}")
  .body("{\"sourceUrl\":\"https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4\", \"language\":\"en\", \"transcriptionType\":\"transcription\"}", \"jobType\":\"direct\", \"numberOfSpeakers    \":\"2\")
  .asJson();

const request = require('request');
const fs = require('fs');

let options = {
  method: 'POST',
  url: 'https://api.amberscript.com/api/jobs/upload-media-from-url',
  body: {
    "sourceUrl": "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4",
    "apiKey": "YOUR_API_KEY",
    "transcriptionType": "transcription",
    "jobType": "direct",
    "language": "nl",
    "numberOfSpeakers": "2"
  },
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = 'https://api.amberscript.com/api/jobs/upload-media-from-url'
query_string = {"apiKey": "YOUR_API_KEY"}
body = {"sourceUrl": "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4", "jobType": "direct",
        "language": "nl", "transcriptionType": "transcription", "numberOfSpeakers": "2"}

response = requests.post(url, verify=False, params=query_string, json=body)

print(response.status_code)
print(response.text)

curl --request POST --url 'https://api.amberscript.com/api/jobs/upload-media-from-url?apiKey={{YOUR_API_KEY}}' \
-H "Content-Type: application/json" \
--data '{"sourceUrl" : "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4","transcriptionType":"transcription","jobType":"direct","language":"nl"}' \

Example: Response to a POST request:

{
  "jobStatus": {
    "jobId": "JOB_ID",
    "created": 82800000,
    "language": "en",
    "notes": null,
    "status": "OPEN",
    "nrAudioSeconds": 45,
    "transcriptionType": "translatedSubtitles",
    "filename": "file_name.mp3",
    "jobType": "perfect",
    "sourceJobId": "SOURCE_JOB_ID", // only present for translated subtitles jobs.
    "targetLanguage": "nl" // OPTIONAL, translatedSubtitles only
  }
}

HTTP Request

POST /jobs/upload-media-from-url

Request Body Parameters

Parameter Default Description/Example
language en af-za, sq-al, am-et, ar, hy-am, az-az, id-id, eu-es, bn-bd, bn-in, bs-ba, bg, my-mm, ca, cmn, hr, cs, da, nl, en-au, en-uk, en, et-ee, fa-ir, fil-ph, fi, nl-be, fr-ca, fr, gl-es, ka-ge, de-at, de-ch, de, el, gu-in, iw-il, hi, hu, is-is, it, ja, jv-id, kn-in, km-kh, ko, lo-la, lv, lt, mk-mk, ms, ml-in, mr-in, mn-mn, ne-np, no, pl, pt-br, pt, pa-guru-in, ro, ru, sr-rs, si-lk, sk, sl, es, su-id, sw-ke, sw-tz, sv, ta-in, ta-my, ta-sg, ta-lk, te-in, th-th, tr, uk-ua, ur-in, ur-pk, uz-uz, vi-vn, zu-za, auto
transcriptionType transcription transcription, captions, translatedSubtitles
jobType direct perfect, direct
numberOfSpeakers 2 1, 2, 3, 4, 5
sourceUrl `` "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4"
callbackUrl (OPTIONAL) NONE YOUR_CALLBACK_URL
transcriptionStyle (OPTIONAL) cleanread cleanread, verbatim
turnaroundTime (OPTIONAL) FIVE_DAYS - transcription/captions, SEVEN_DAYS - translatedSubtitles Hint: Get in touch if you need a turnaround time other than the default one.
targetLanguage (OPTIONAL) NONE pl, en, ru, fr-ca, ca, zh, ga, hu, pt, da, de-at, fr, nl, en-au, ko, it, de, fi, cmn, ja, de-ch, en-us, ro, pt-br, nl-be, cs, no, sv, en-uk, es

Uploading With callbackUrl

  1. When you make a request with a callbackUrl, we send the final status of your upload to this url.
  2. When processing is complete, this status is sent via a POST request (see below).
  1. Your callbackUrl endpoint should respond with any 2xx if you successfully receive the status.

There are times when our system can encounter issues with your job. When that is the case, the callback will be sent with an ERROR status, and the content of the callback will look like this:

{
  "jobId": "JOB_ID",
  "created": 82800000,
  "language": "nl",
  "status": "ERROR",
  "nrAudioSeconds": 45,
  "transcriptionType": "transcription",
  "filename": "file_name.mp3",
  "jobType": "direct",
  "errorMsg": "No speech found"
}

Otherwise, you will get a callback informing you that your job was successfully transcribed.

{
  "jobId": "JOB_ID",
  "created": 82800000,
  "language": "nl",
  "status": "DONE",
  "nrAudioSeconds": 45,
  "transcriptionType": "captions",
  "filename": "file_name.mp3",
  "jobType": "direct"
}

Uploading Without callbackUrl

  1. When you make a request without the callbackUrl, store the value of the jobId returned upon a successful call ( see Example in right pane).
  2. Use the jobId to periodically check the status of the upload request ( e.g. every 5 mins).

Automatic language identification

You can let the automatic speech recognition engine determine the language of uploaded media automatically. To do so, you need to set the value of language request parameter to auto. - Supported languages: English, Dutch, German, French and Italian

Note: Automatic language predictions can be wrong and manual specification is recommended. If you need support or have an issue, please get in touch with us via info@amberscript.com.

File requirements:

If you need support for a different file format, please get in touch with us: info (at) amberscript (dot) com

Request for translated subtitles for an existing manual captions job

HttpResponse<String> response = Unirest.post("https://api.amberscript.com/api/jobs/translatedSubtitles?sourceJobId=SOURCE_JOB_ID&targetLanguage=nl&apiKey=YOUR_API_KEY")
  .asString();

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.amberscript.com/api/jobs/translatedSubtitles',
  qs: {sourceJobId: 'SOURCE_JOB_ID', targetLanguage: 'nl', apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/jobs/translatedSubtitles"

querystring = {"sourceJobId":"SOURCE_JOB_ID","targetLanguage":"nl","apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("POST", url, data=payload, params=querystring)

print(response.text)

curl --request POST --url 'https://api.amberscript.com/api/jobs/translatedSubtitles?sourceJobId=SOURCE_JOB_ID&targetLanguage=nl&apiKey=YOUR_API_KEY'

The command returns JSON structured like this:

{
  "jobStatus": {
    "jobId": "JOB_ID",
    "created": 82800000,
    "language": "en",
    "status": "BUSY",
    "nrAudioSeconds": 45,
    "transcriptionType": "translatedSubtitles",
    "filename": "file_name.mp3",
    "jobType": "perfect",
    "sourceJobId": "SOURCE_JOB_ID",
    "targetLanguage": "nl",
    "notes": "job_notes"
  }
}

Request for translated subtitles with uploaded file.

HTTP Request

POST /jobs/translatedSubtitles

Query Parameters

Parameter Default Description/Example
sourceJobId NONE SOURCE_JOB_ID
targetLanguage pl, en, ru, fr-ca, ca, zh, ga, hu, pt, da, de-at, fr, nl, en-au, ko, it, de, fi, cmn, ja, de-ch, en-us, ro, pt-br, nl-be, cs, no, sv, en-uk, es
turnaroundTime (OPTIONAL) SEVEN_DAYS Hint: Get in touch if you need a turnaround time other than the default one.
callbackUrl (OPTIONAL) NONE YOUR_CALLBACK_URL
notes (OPTIONAL) NONE Job notes

Getting The Status Of A Transcription

HttpResponse<String> response = Unirest.get("https://api.amberscript.com/api/jobs/status?jobId=JOB_ID&apiKey=YOUR_API_KEY")
  .asString();

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.amberscript.com/api/jobs/status',
  qs: {jobId: 'JOB_ID', apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/jobs/status"

querystring = {"jobId":"JOB_ID","apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("GET", url, data=payload, params=querystring)

print(response.text)

curl --request GET --url 'https://api.amberscript.com/api/jobs/status?jobId=JOB_ID&apiKey=YOUR_API_KEY'

The above command returns JSON structured like this:

{
  "jobStatus": {
    "jobId": "JOB_ID",
    "created": 82800000,
    "language": "en",
    "status": "OPEN",
    "jobOptions": {
      "transcriptionStyle": "verbatim" // job options are only present if explicitly requests
    },
    "nrAudioSeconds": 45,
    "transcriptionType": "transcription",
    "filename": "file_name.mp3",
    "jobType": "direct",
    "sourceJobId": "SOURCE_JOB_ID",    // OPTIONAL, translatedSubtitles only
    "targetLanguage": "nl" // OPTIONAL, translatedSubtitles only
    "notes": "job_notes"
  }
}

Retrieve the status of a specific job.

HTTP Request

GET /jobs/status

Query Parameters

Parameter Default Description/Example
jobId NONE YOUR_JOB_ID

Exporting

Export To STL

HttpResponse<String> response = Unirest.get("https://api.amberscript.com/api/jobs/export-stl?jobId=JOB_ID&apiKey=YOUR_API_KEY")
  .asString();

 var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.amberscript.com/api/jobs/export-stl',
  qs: {jobId: 'JOB_ID', apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/jobs/export-stl"

querystring = {"jobId":"JOB_ID" "apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("GET", url, data=payload, params=querystring)

print(response.text)

curl --request GET --url 'https://api.amberscript.com/api/jobs/export-stl?jobId=JOB_ID&apiKey=YOUR_API_KEY'

The above command returns a JSON downloadUrl structured like this:

{
  "downloadUrl": "https://PROD-SERVER/ebu-stl/FILENAME?X-Amz-Algorithm=HASH_ALGORITHM&X-Amz-Date=CURRENT_DATE&X-Amz-SignedHeaders=host&X-Amz-Expires=TIME_TO_EXPIRATION&X-Amz-Credential=AMZ_CREDENTIAL&X-Amz-Signature=AMZ_SIGNATURE"
}

Export a finished file to STL.

HTTP Request

GET /jobs/export-stl

Query Parameters

Parameter Default Description/Example
jobId NONE YOUR_JOB_ID
maxNumberOfRows (OPTIONAL) 2 Integer between 1 and 2 which sets the maximum number of rows for each subtitle.
maxScreenTimePerRowSeconds (OPTIONAL) 2 Float which sets the maximum number of seconds given for each row of subtitles.

Export To SRT

HttpResponse<String> response = Unirest.get("https://api.amberscript.com/api/jobs/export-srt?jobId=JOB_ID&apiKey=YOUR_API_KEY")
  .asString();

 var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.amberscript.com/api/jobs/export-srt',
  qs: {jobId: 'JOB_ID', apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/jobs/export-srt"

querystring = {"jobId":"JOB_ID" "apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("GET", url, data=payload, params=querystring)

print(response.text)

curl --request GET --url 'https://api.amberscript.com/api/jobs/export-srt?jobId=JOB_ID&apiKey=YOUR_API_KEY'

The command returns SRT structured like this:

1
00:00:00,449 --> 00:00:03,769
Hi, welcome to Amber script, in this short

2
00:00:03,869 --> 00:00:07,400
video, we would like to show you how
you can use Amber script at its full

3
00:00:07,500 --> 00:00:10,189
potential. The first
function we would like to show

4
00:00:10,289 --> 00:00:13,639
you is the edit function.
This allows you to edit errors

Export a finished file to SRT.

HTTP Request

GET /jobs/export-srt

Query Parameters

Parameter Default Description/Example
jobId NONE YOUR_JOB_ID
maxCharsPerRow (OPTIONAL) 42 Integer between 30 and 45 which sets the maximum number of characters per row.
maxNumberOfRows (OPTIONAL) 2 Integer between 1 and 2 which sets the maximum number of rows for each subtitle.
maxScreenTimePerRowSeconds (OPTIONAL) 2 Float which sets the maximum number of seconds given for each row of subtitles.

Export To VTT

HttpResponse<String> response = Unirest.get("https://api.amberscript.com/api/jobs/export-vtt?jobId=JOB_ID&apiKey=YOUR_API_KEY")
  .asString();

 var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.amberscript.com/api/jobs/export-vtt',
  qs: {jobId: 'JOB_ID', apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/jobs/export-vtt"

querystring = {"jobId":"JOB_ID" "apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("GET", url, data=payload, params=querystring)

print(response.text)

curl --request GET --url 'https://api.amberscript.com/api/jobs/export-vtt?jobId=JOB_ID&apiKey=YOUR_API_KEY'

The command returns VTT structured like this:

WEBVTT - created by www.amberscript.com

1
00:00:00.449 --> 00:00:03.769
Hi, welcome to Amber script, in this short

2
00:00:03.869 --> 00:00:07.400
video, we would like to show you how
you can use Amber script at its full

3
00:00:07.500 --> 00:00:10.189
potential. The first
function we would like to show

4
00:00:10.289 --> 00:00:13.639
you is the edit function.
This allows you to edit errors

Export a finished file to VTT.

HTTP Request

GET /jobs/export-vtt

Query Parameters

Parameter Default Description/Example
jobId NONE YOUR_JOB_ID
maxCharsPerRow (OPTIONAL) 42 Integer between 30 and 45 which sets the maximum number of characters per row.
maxNumberOfRows (OPTIONAL) 2 Integer between 1 and 2 which sets the maximum number of rows for each subtitle.
maxScreenTimePerRowSeconds (OPTIONAL) 2 Float which sets the maximum number of seconds given for each row of subtitles.

Export To TEXT

HttpResponse<String> response = Unirest.get("https://api.amberscript.com/api/jobs/export-txt?jobId=JOB_ID&apiKey=YOUR_API_KEY")
  .asString();

 var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.amberscript.com/api/jobs/export-txt',
  qs: {jobId: 'JOB_ID', apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/jobs/export-txt"

querystring = {"jobId":"JOB_ID" "apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("GET", url, data=payload, params=querystring)

print(response.text)

curl --request GET --url 'https://api.amberscript.com/api/jobs/export-txt?jobId=JOB_ID&apiKey=YOUR_API_KEY'

The command returns TXT structured like this:

00:00:00
Speaker 1: Hi, welcome to Amber script, in this short video, we would like to show you how you can use Amber script at its full potential. The first function we would like to show you is the edit function. This allows you to edit errors

Export a finished file to TEXT.

HTTP Request

GET /jobs/export-txt

Query Parameters

Parameter Default Description/Example
jobId NONE YOUR_JOB_ID
includeTimestamps (OPTIONAL) true Boolean.
includeSpeakers (OPTIONAL) true Boolean.
highlightsOnly (OPTIONAL) false Boolean.
maxCharsPerRow (OPTIONAL) NONE Integer which sets the maximum number of characters per row.

Export To JSON

HttpResponse<String> response = Unirest.get("https://api.amberscript.com/api/jobs/export-json?jobId=JOB_ID&apiKey=YOUR_API_KEY")
  .asString();

 var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.amberscript.com/api/jobs/export-json',
  qs: {jobId: 'JOB_ID', apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/jobs/export-json"

querystring = {"jobId":"JOB_ID" "apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("GET", url, data=payload, params=querystring)

print(response.text)

curl --request GET --url 'https://api.amberscript.com/api/jobs/export-json?jobId=JOB_ID&apiKey=YOUR_API_KEY'

The command returns JSON structured like this:

{
  "id": "5c9e45057103e464a4c6f477",
  "recordId": "RECORD_ID",
  "filename": "FILENAME",
  "startTimeOffset": 0.0,
  "speakers": [
    {
      "spkid": "spk1",
      "name": "Speaker 1"
    }
  ],
  "segments": [
    {
      "speaker": "spk1",
      "words": [
        {
          "start": 0.45,
          "end": 1.08,
          "duration": 0.63000005,
          "text": "Hi,",
          "conf": 1.0,
          "pristine": true
        },
        {
          "start": 1.11,
          "end": 1.65,
          "duration": 0.53999996,
          "text": "welcome",
          "conf": 1.0,
          "pristine": true
        },
        {
          "start": 1.65,
          "end": 1.8,
          "duration": 0.14999998,
          "text": "to",
          "conf": 1.0,
          "pristine": true
        },
        {
          "start": 1.8,
          "end": 2.1,
          "duration": 0.29999995,
          "text": "Amberscript",
          "conf": 0.65,
          "pristine": true
        }
      ]
    }
  ],
  "highlights": []
}

Export a finished file to JSON.

HTTP Request

GET /jobs/export-json

Query Parameters

Parameter Default Description/Example
jobId NONE YOUR_JOB_ID

Listing and deleting jobs

Delete A Job

HttpResponse<String> response = Unirest.delete("https://api.amberscript.com/api/jobs?jobId=JOB_ID&apiKey=YOUR_API_KEY")
  .asString();

 var request = require("request");

var options = {
  method: 'DELETE',
  url: 'https://api.amberscript.com/api/jobs',
  qs: {jobId: 'JOB_ID', apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/jobs"

querystring = {"jobId":"JOB_ID" "apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("DELETE", url, data=payload, params=querystring)

print(response.text)

curl --request DELETE --url 'https://api.amberscript.com/api/jobs?jobId=JOB_ID&apiKey=YOUR_API_KEY'

The command returns JSON structured like this:

{
  "message": "Job deleted"
}

Delete a specific job.

HTTP Request

DELETE /jobs

Query Parameters

Parameter Default Description/Example
jobId NONE YOUR_JOB_ID

Get List Of Jobs

HttpResponse<String> response = Unirest.get("https://api.amberscript.com/api/jobs?apiKey=YOUR_API_KEY")
  .asString();

 var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.amberscript.com/api/jobs',
  qs: {apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/jobs"

querystring = {"apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("GET", url, data=payload, params=querystring)

print(response.text)

curl --request GET --url 'https://api.amberscript.com/api/jobs?apiKey=YOUR_API_KEY'

The command returns JSON structured like this:

[
  {
    "jobId": "5f686d2d8c996402a02bbb92",
    "created": 1600679213751,
    "language": "nl",
    "status": "DONE",
    "nrAudioSeconds": 59,
    "transcriptionType": "transcription",
    "filename": "test.mp4",
    "jobType": "perfect",
    "jobOptions": {
      "transcriptionStyle": "cleanread"
    },
    "notes": null
  },
  {
    "jobId": "5f686d068c996402a02bbb85",
    "created": 1600679174451,
    "language": "nl",
    "status": "DONE",
    "nrAudioSeconds": 191,
    "transcriptionType": "transcription",
    "filename": "test.mp4",
    "jobType": "perfect",
    "jobOptions": {
      "transcriptionStyle": "cleanread"
    },
    "notes": null
  },
  {
    "jobId": "5f686d068c996402a02bbb82",
    "created": 1600679174415,
    "language": "nl",
    "status": "DONE",
    "nrAudioSeconds": 59,
    "transcriptionType": "transcription",
    "filename": "test.mp4",
    "jobType": "perfect",
    "jobOptions": {
      "transcriptionStyle": "cleanread"
    },
    "notes": null
  }
]

Get a list of jobs.

HTTP Request

GET /jobs

Query Parameters

Parameter Default Description/Example
jobId (OPTIONAL) NONE YOUR_JOB_ID
jobType (OPTIONAL) NONE Type of the job e.g. perfect.
status (OPTIONAL) NONE OPEN, ERROR or DONE.
transcriptionType (OPTIONAL) NONE Type of transcription e.g. transcription.
page (OPTIONAL) 0 Page to be retrieved.
pageSize (OPTIONAL) 20 Number of records to be retrieved for each page (maximum: 100).

Glossary

You can make use of the glossary feature to help improve the quality of your transcription, captions, and translated subtitles. If you already know the names of people/places/organizations, technical terms, or domain-specific terms that are spoken in the media file, these can be added to the glossary to improve the automatic recognition of these terms. Furthermore, for manual services, the glossary is used to aid transcribers in perfecting the file.

Best practices for creating a glossary:

Get a list of glossaries

HttpResponse<String> response = Unirest.get("https://api.amberscript.com/api/glossary?apiKey=YOUR_API_KEY")
  .asString();

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.amberscript.com/api/glossary',
  qs: {apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/glossary"

querystring = {"apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("GET", url, data=payload, params=querystring)

print(response.text)

curl --request GET --url 'https://api.amberscript.com/api/glossary?apiKey=YOUR_API_KEY'

The command returns JSON structured like this:

[
  {
    "id": "5f686d068c996402a02bbb85",
    "userName": "YOUR_USERNAME",
    "name": "Name of first glossary",
    "names": [
      "Test name one",
      "Test name two"
    ],
    "items":[
      {
        "name": "Item one name",
        "description": "description of item one"
      },
      {
        "name": "Item two name",
        "description": "description of item two"
      }
    ],
    "created": 1600679174451
  },
  {
    "id": "5f686d068c996402a02bbb86",
    "userName": "YOUR_USERNAME",
    "name": "Name of second glossary",
    "names": [
      "Test name one",
      "Test name two"
    ],
    "items":[
      {
        "name": "Item one name",
        "description": "description of item one"
      },
      {
        "name": "Item two name",
        "description": "description of item two"
      }
    ],
    "created": 1600679175000
  }
]

Get a list of glossaries.

HTTP Request

GET /glossary

Query Parameters

Parameter Default Description/Example
sortBy (OPTIONAL) "created" Field by which to sort the resulting list of glossaries.
sortDirection (OPTIONAL) DESC DESC or ASC

Create a glossary

String body = "{\n" +
    "  \"name\": \"Name of first glossary\",\n" +
    "  \"names\": [\n" +
    "    \"Test name one\",\n" +
    "    \"Test name two\"\n" +
    "  ],\n" +
    "  \"items\": [\n" +
    "    {\n" +
    "      \"name\": \"Item one name\",\n" +
    "      \"description\": \"description of item one\"\n" +
    "    },\n" +
    "    {\n" +
    "      \"name\": \"Item two name\",\n" +
    "      \"description\": \"description of item two\"\n" +
    "    }\n" +
    "  ]\n" +
    "}";
HttpResponse<String> response = Unirest.post("https://api.amberscript.com/api/glossary?apiKey=YOUR_API_KEY")
  .header("Content-Type", "application/json")
  .body(body)
  .asString();

var request = require("request");

var body = {
  "name": "Name of first glossary",
  "names": [
    "Test name one",
    "Test name two"
  ],
  "items": [
    {
      "name": "Item one name",
      "description": "description of item one"
    },
    {
      "name": "Item two name",
      "description": "description of item two"
    }
  ]
}

var options = {
  method: 'POST',
  url: 'https://api.amberscript.com/api/glossary',
  headers: {
    'Content-Type': 'application/json'
  },
  qs: {apiKey: 'YOUR_API_KEY'},
  body: body
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/glossary"

querystring = {"apiKey":"YOUR_API_KEY"}

payload = "{\n" \
          "  \"name\": \"Name of first glossary\",\n" \
          "  \"names\": [\n" \
          "    \"Test name one\",\n" \
          "    \"Test name two\"\n" \
          "  ],\n" \
          "  \"items\": [\n" \
          "    {\n" \
          "      \"name\": \"Item one name\",\n" \
          "      \"description\": \"description of item one\"\n" \
          "    },\n" \
          "    {\n" \
          "      \"name\": \"Item two name\",\n" \
          "      \"description\": \"description of item two\"\n" \
          "    }\n" \
          "  ]\n" \
          "}"

headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, data=payload, headers=headers, params=querystring)

print(response.text)

curl --request POST --url 'https://api.amberscript.com/api/glossary?apiKey=YOUR_API_KEY' --header 'Content-Type: application/json' --data-raw '{
    "name":"Name of first glossary",
    "names": [
      "Test name one",
      "Test name two"
    ],
    "items":[
        {
            "name":{{glossaryItem1Name}},
            "description":{{glossaryItem1Description}}
        },
        {
            "name":"{{glossaryItem2Name}}",
            "description":{{glossaryItem2Description}}
        }
    ]
}'

The command returns JSON structured like this:

{
  "id": "5f686d068c996402a02bbb85",
  "userName": "YOUR_USERNAME",
  "name": "Name of first glossary",
  "names": [
    "Test name one",
    "Test name two"
  ],
  "items":[
    {
      "name": "Item one name",
      "description": "description of item one"
    },
    {
      "name": "Item two name",
      "description": "description of item two"
    }
  ],
  "created": 1600679174451
}

Create a glossary.

HTTP Request

POST /glossary

Body JSON

UserGlossary

Attribute Type Description Required
name string
maxLength: 60		 Name of the glossary. Yes
names [string]
maxItems: 250
maxItemLength: 20		 Array of names. No
items [object]
maxItems: 750		 Array of glossary items. GlossaryItem format is described in the table below. No

GlossaryItem

Attribute Type Description Required
item.name string
maxLength: 60		 Term which is being described. Yes
item.description string
maxLength: 200		 Description of the term. No

Update a glossary

String body = "{\n" +
    "  \"name\": \"Name of first glossary\",\n" +
    "  \"names\": [\n" +
    "    \"Test name one\",\n" +
    "    \"Test name two\"\n" +
    "  ],\n" +
    "  \"items\": [\n" +
    "    {\n" +
    "      \"name\": \"Item one name\",\n" +
    "      \"description\": \"description of item one\"\n" +
    "    },\n" +
    "    {\n" +
    "      \"name\": \"Item two name\",\n" +
    "      \"description\": \"description of item two\"\n" +
    "    }\n" +
    "  ]\n" +
    "}";
HttpResponse<String> response = Unirest.put("https://api.amberscript.com/api/glossary/GLOSSARY_ID?apiKey=YOUR_API_KEY")
  .header("Content-Type", "application/json")
  .body(body)
  .asString();

var request = require("request");

var body = {
  "name": "Name of first glossary",
  "names": [
    "Test name one",
    "Test name two"
  ],
  "items": [
    {
      "name": "Item one name",
      "description": "description of item one"
    },
    {
      "name": "Item two name",
      "description": "description of item two"
    }
  ]
}

var options = {
  method: 'PUT',
  url: 'https://api.amberscript.com/api/glossary/GLOSSARY_ID',
  headers: {
    'Content-Type': 'application/json'
  },
  qs: {apiKey: 'YOUR_API_KEY'},
  body: body
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/glossary/GLOSSARY_ID"

querystring = {"apiKey":"YOUR_API_KEY"}

payload = "{\n" \
          "  \"name\": \"Name of first glossary\",\n" \
          "  \"names\": [\n" \
          "    \"Test name one\",\n" \
          "    \"Test name two\"\n" \
          "  ],\n" \
          "  \"items\": [\n" \
          "    {\n" \
          "      \"name\": \"Item one name\",\n" \
          "      \"description\": \"description of item one\"\n" \
          "    },\n" \
          "    {\n" \
          "      \"name\": \"Item two name\",\n" \
          "      \"description\": \"description of item two\"\n" \
          "    }\n" \
          "  ]\n" \
          "}"

headers = {
  'Content-Type': 'application/json'
}

response = requests.request("PUT", url, data=payload, headers=headers, params=querystring)

print(response.text)

curl --request PUT --url 'https://api.amberscript.com/api/glossary/GLOSSARY_ID?apiKey=YOUR_API_KEY' --header 'Content-Type: application/json' --data-raw '{
    "name":"Name of first glossary",
    "names": [
      "Test name one",
      "Test name two"
    ],
    "items":[
        {
            "name":{{glossaryItem1Name}},
            "description":{{glossaryItem1Description}}
        },
        {
            "name":"{{glossaryItem2Name}}",
            "description":{{glossaryItem2Description}}
        }
    ]
}'

The command returns JSON structured like this:

{
  "id": "5f686d068c996402a02bbb85",
  "userName": "YOUR_USERNAME",
  "name": "Name of first glossary",
  "names": [
    "Test name one",
    "Test name two"
  ],
  "items":[
    {
      "name": "Item one name",
      "description": "description of item one"
    },
    {
      "name": "Item two name",
      "description": "description of item two"
    }
  ],
  "created": 1600679174451
}

Update a specific glossary.

HTTP Request

PUT /glossary/GLOSSARY_ID

Body JSON

UserGlossary

Attribute Type Description Required
name string
maxLength: 60		 Name of the glossary. Yes
names [string]
maxItems: 250
maxItemLength: 20		 Array of names. No
items [object]
maxItems: 750		 Array of glossary items. GlossaryItem format is described in the table below. No

GlossaryItem

Attribute Type Description Required
item.name string
maxLength: 60		 Term which is being described. Yes
item.description string
maxLength: 200		 Description of the term. No

Delete a glossary

HttpResponse<String> response = Unirest.delete("https://api.amberscript.com/api/glossary/GLOSSARY_ID?apiKey=YOUR_API_KEY")
  .asString();

var request = require("request");

var options = {
  method: 'DELETE',
  url: 'https://api.amberscript.com/api/glossary/GLOSSARY_ID',
  qs: {apiKey: 'YOUR_API_KEY'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

import requests

url = "https://api.amberscript.com/api/glossary/GLOSSARY_ID"

querystring = {"apiKey":"YOUR_API_KEY"}

payload = ""
response = requests.request("DELETE", url, data=payload, params=querystring)

print(response.text)

curl --request DELETE --url 'https://api.amberscript.com/api/glossary/GLOSSARY_ID?apiKey=YOUR_API_KEY'

Delete a specific glossary.

HTTP Request

DELETE /glossary/GLOSSARY_ID

Support

If you need any technical assistance, feel free to contact info (at) amberscript (dot) com

Errors

Amberscript API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. Please check your request body and/or parameters.
401 Unauthorized -- Your API key is invalid.
403 Forbidden -- You do have access to requested resource.
404 Not Found -- The requested resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
429 Too Many Requests -- Rate limit reached
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
NodeJS Java Python cURL