Transcription API (v4)

Introduction

Using GoTranscript API you can submit files for:

  • transcription (audio/video files)
  • translation (documents/audio/video files)
  • captioning (audio/video files)
  • subtitling (audio/video files)

How it works?

workflow
  • 1. Your server sends url of a file you want to transcribe.
  • 2. When transcription is finished, GoTranscript will send url of transcription back to you.

When you will make an order, money will be deducted from your GoTranscript wallet.

Authentication

Authentication is done with an api_token parameter given in the request body.
Your api_token is: login_to_see_token

HTTP Statuses

if returned status code is 200, it indicates that the request was fulfilled successfully and that no error was encountered.

if you receive a status code 400, it typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, or that your request is malformed.

Return codes in the 500 range typically indicate that there is a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.

Responses

When a request is successful, a response body will typically be sent back in the form of a JSON object. Please take a look at API calls to see what data object will be given. In case of error, standard response object will be given:


// HTTP 400 Bad Request Error Response
{
    'mode' => 'string',
    'status' => 'string',
    'error' => 'string'
}

Callbacks

GoTranscript uses callbacks to notify your application when your requested job is done. With every API request, an additional callback_url parameter can be given. The value of this parameter must be a valid HTTP URL address, which must be able to handle POST requests.

Set your website url down below.

In case you dont want to pass callback_url parameter in every API call, you can set it globally here:

Login to set global callback URL

When your application receives a callback, it must output string ok. If it will not output ok, request will be repeated again every hour up to 10 times.

Transcription

Send POST request to GoTranscript to order transcription.

Request example


    curl -X POST \
      -H "Content-Type: application/json" \
      -d '{"mode":"test", "url": "https://gotranscript.com/tests/api/audio.mp3", "language": "english", "api_token": "login_to_see_token"}' \
      "https://gotranscript.com/api/v4/transcriptions"
                            

    $curl = curl_init();

    curl_setopt_array($curl, [
      CURLOPT_URL => 'https://gotranscript.com/api/v4/transcriptions',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => json_encode(
        [
            'mode' => 'test',
            'url' => 'https://gotranscript.com/tests/api/audio.mp3', // your file url
            'language' => 'english',
            'api_token' => 'login_to_see_token', // this is your API token
        ]
      ),
      CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
      ]
    ]);

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if ($err) {
      echo 'cURL Error #:' . $err;
    } else {
      echo $response;
    }
                            

    import requests

    endpoint = "https://gotranscript.com/api/v4/transcriptions"

    json = {
        'mode': 'test',
        'url': 'https://gotranscript.com/tests/api/audio.mp3',
        'language': 'english',
        'api_token': 'login_to_see_token',
    }

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

    response = requests.post(endpoint, json=json, headers=headers)
    parse(response)
                            

    const axios = require("axios");

    const assembly = axios.create({
      baseURL: "https://gotranscript.com",
      headers: {
        "Content-Type": "application/json"
      }
    });

    assembly
      .post("/api/v4/transcriptions", {
        mode: "test",
        url: "https://gotranscript.com/tests/api/audio.mp3",
        language: "english",
        api_token: "login_to_see_token"
      })
      .then(parseResponse)
      .catch(console.error);

Request parameters

Name Type Description
api_token String Your API token. Your current API token is: login_to_see_token.
mode String Can be one of the following: test, live. When set to test, file price is calculated but not charged from your wallet. This way you can test how much it will cost to make an order. When you want to make a real order, change test to live.
url String File url you want to transcribe.
language String Language of file. List of available languages: english,albanian,arabic,armenian,azerbaijani,bengali,bosnian,bulgarian,catalan,chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,georgian,german,greek,hebrew,hungarian,indian,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-dari,persian-farsi,polish,portuguese,romanian,russian,serbian,shona,slovak,slovenian,somali,spanish,swahili,swedish,tajik,thai,turkish,turkmen,ukrainian,urdu,uzbek,vietnamese.
comment String Here you can specify names of speakers or other information for transcribers.
from Integer Start file transcription from this amount of seconds.
till Integer Finish file transcription at this amount of seconds.
text_format String Available values: clean_verbatim (default), full_verbatim
timestamping String Available values: not_required (default), every_10_seconds , every_30_seconds , every_2_minutes , change_of_speaker
turnaround_time String Available values: 12_hours, 1_days, 3_days, 5_days(default)
number_of_speakers String Available values: 1_or_2 (default), 3_or_more
callback_url String When order is finished, you can specify url which will be used for callback.

Response body

Response will be in JSON format.


    {
       "mode":"live",
       "status":"success",
       "order_id":123, // order_id will be set only when wallet is charged (live mode)
       "order_total":12.34 // $12.34 dollars
       "seconds":68, // order duration in seconds
       "in_wallet":0, // how much money you have left in your GoTranscript wallet
       "delivery_estimate":"2022-11-30 14:02:44", // (UTC time)
    }

Callback

When file transcription is finished, POST request will be sent to your specified URL. It will contain JSON:


    {
        'mode' => 'live',
        'order_id' => 123,
        'transcription_url' => 'https://gotranscript.com/api/v4/test-file/transcriptions?api_token=login_to_see_token',
        'language' => 'english', // language of transcription
    }

Transcription file format. transcription_url returns .docx document. You can also get transcription in different formats by adding parameter to transcription_url: docx, doc, pdf, text, html or json
Example: https://gotranscript.com/api/v4/test-file/transcriptions?api_token=login_to_see_token&format=json

To test how your server responds to request from gotranscript.com, click on the link below.

Send test response to your server

Translation

Send POST request to GoTranscript to order translation.

Request example


    curl -X POST \
      -H "Content-Type: application/json" \
      -d '{"mode":"test", "url": "https://gotranscript.com/tests/api/audio.mp3", "translate_from": "english", "translate_to": "german", "api_token": "login_to_see_token"}' \
      "https://gotranscript.com/api/v4/translations"
                            

    $curl = curl_init();

    curl_setopt_array($curl, [
      CURLOPT_URL => 'https://gotranscript.com/api/v4/translations',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => json_encode(
        [
            'mode' => 'test',
            'url' => 'https://gotranscript.com/tests/api/audio.mp3', // your file url
            'translate_from' => 'english',
            'translate_to' => 'german',
            'api_token' => 'login_to_see_token', // this is your API token
        ]
      ),
      CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
      ]
    ]);

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if ($err) {
      echo 'cURL Error #:' . $err;
    } else {
      echo $response;
    }
                            

    import requests

    endpoint = "https://gotranscript.com/api/v4/translations"

    json = {
        'mode': 'test',
        'url': 'https://gotranscript.com/tests/api/audio.mp3',
        'translate_from': 'english',
        'translate_to': 'german',
        'api_token': 'login_to_see_token',
    }

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

    response = requests.post(endpoint, json=json, headers=headers)
    parse(response)
                            

    const axios = require("axios");

    const assembly = axios.create({
      baseURL: "https://gotranscript.com",
      headers: {
        "Content-Type": "application/json"
      }
    });

    assembly
      .post("/api/v4/translations", {
        mode: "test",
        url: "https://gotranscript.com/tests/api/audio.mp3",
        translate_from: "english",
        translate_to: "german",
        api_token: "login_to_see_token"
      })
      .then(parseResponse)
      .catch(console.error);

Request parameters

Name Type Description
api_token String Your API token. Your current API token is: login_to_see_token.
mode String Can be one of the following: test, live. When set to test, file price is calculated but not charged from your wallet. This way you can test how much it will cost to make an order. When you want to make a real order, change test to live.
url String File url you want to translate.
translate_from String Translate from the given file text language. List of available languages: english,albanian,arabic,armenian,azerbaijani,bengali,bosnian,bulgarian,catalan,chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,georgian,german,greek,hebrew,hungarian,indian,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-dari,persian-farsi,polish,portuguese,romanian,russian,serbian,shona,slovak,slovenian,somali,spanish,swahili,swedish,tajik,thai,turkish,turkmen,ukrainian,urdu,uzbek,vietnamese.
translate_to String Translate the given file text to a given language. List of available languages: english,albanian,arabic,armenian,azerbaijani,bengali,bosnian,bulgarian,catalan,chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,georgian,german,greek,hebrew,hungarian,indian,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-dari,persian-farsi,polish,portuguese,romanian,russian,serbian,shona,slovak,slovenian,somali,spanish,swahili,swedish,tajik,thai,turkish,turkmen,ukrainian,urdu,uzbek,vietnamese.
comment String Here you can specify additional information for translators.
callback_url String When order is finished, you can specify url which will be used for callback.

Response body

Response will be in JSON format.


    {
       "mode":"live",
       "status":"success",
       "order_id":123, // order_id will be set only when wallet is charged (live mode)
       "order_total":12.34 // $12.34 dollars
       "seconds":0, // order duration in seconds
       "words":68, // order word count
       "in_wallet":0, // how much money you have left in your GoTranscript wallet
       "delivery_estimate":"2022-11-30 14:02:44", // (UTC time)
    }

Callback

When file transcription is finished, POST request will be sent to your specified URL. It will contain JSON:


    {
        'mode' => 'live',
        'order_id' => 123,
        'translation_url' => 'https://gotranscript.com/api/v4/test-file/translations?api_token=login_to_see_token'
    }

To test how your server responds to request from gotranscript.com, click on the link below.

Send test response to your server

Captions Example

Send POST request to GoTranscript to order captions.

Request example


    curl -X POST \
      -H "Content-Type: application/json" \
      -d '{"mode":"test", "url": "https://gotranscript.com/tests/api/audio.mp3", "language": "english", "api_token": "login_to_see_token"}' \
      "https://gotranscript.com/api/v4/captions"
                            

    $curl = curl_init();

    curl_setopt_array($curl, [
      CURLOPT_URL => 'https://gotranscript.com/api/v4/captions',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => json_encode(
        [
            'mode' => 'test',
            'url' => 'https://gotranscript.com/tests/api/audio.mp3', // your file url
            'language' => 'english',
            'api_token' => 'login_to_see_token', // this is your API token
        ]
      ),
      CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
      ]
    ]);

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if ($err) {
      echo 'cURL Error #:' . $err;
    } else {
      echo $response;
    }
                            

    import requests

    endpoint = "https://gotranscript.com/api/v4/captions"

    json = {
        'mode': 'test',
        'url': 'https://gotranscript.com/tests/api/audio.mp3',
        'language': 'english',
        'api_token': 'login_to_see_token',
    }

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

    response = requests.post(endpoint, json=json, headers=headers)
    parse(response)
                            

    const axios = require("axios");

    const assembly = axios.create({
      baseURL: "https://gotranscript.com",
      headers: {
        "Content-Type": "application/json"
      }
    });

    assembly
      .post("/api/v4/captions", {
        mode: "test",
        url: "https://gotranscript.com/tests/api/audio.mp3",
        language: "english",
        api_token: "login_to_see_token"
      })
      .then(parseResponse)
      .catch(console.error);

Request parameters

Name Type Description
api_token String Your API token. Your current API token is: login_to_see_token.
mode String Can be one of the following: test, live. When set to test, file price is calculated but not charged from your wallet. This way you can test how much it will cost to make an order. When you want to make a real order, change test to live.
url String File url you want to make captions for.
language String Language of file. List of available languages: english,albanian,arabic,armenian,azerbaijani,bengali,bosnian,bulgarian,catalan,chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,georgian,german,greek,hebrew,hungarian,indian,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-dari,persian-farsi,polish,portuguese,romanian,russian,serbian,shona,slovak,slovenian,somali,spanish,swahili,swedish,tajik,thai,turkish,turkmen,ukrainian,urdu,uzbek,vietnamese.
comment String Here you can specify names of speakers or other information for subtitlers.
from Integer Start file transcription from this amount of seconds.
till Integer Finish file transcription at this amount of seconds.
text_format String Available values: clean_verbatim (default), full_verbatim
timestamping String Available values: not_required (default), every_10_seconds , every_30_seconds , every_2_minutes , change_of_speaker
turnaround_time String Available values: 12_hours, 1_days, 3_days, 5_days(default)
number_of_speakers String Available values: 1_or_2 (default), 3_or_more
callback_url String When order is finished, you can specify url which will be used for callback.

Response body

Response will be in JSON format.


    {
       "mode":"live",
       "status":"success",
       "order_id":123, // order_id will be set only when wallet is charged (live mode)
       "order_total":12.34 // $12.34 dollars
       "seconds":68, // order duration in seconds
       "in_wallet":0, // how much money you have left in your GoTranscript wallet
       "delivery_estimate":"2022-11-30 14:02:44", // (UTC time)
    }

Callback

When file transcription is finished, POST request will be sent to your specified URL. It will contain JSON:


    {
        'mode' => 'live',
        'order_id' => 123,
        'captions_url' => 'https://gotranscript.com/api/v4/test-file/captions?api_token=login_to_see_token',
        'transcription_url' => 'https://gotranscript.com/api/v4/test-file/transcriptions?api_token=login_to_see_token',
        'language' => 'english' // language of captions
    }

To test how your server responds to request from gotranscript.com, click on the link below.

Send test response to your server

Subtitles Example

Send POST request to GoTranscript to order subtitles.

Request example


    curl -X POST \
      -H "Content-Type: application/json" \
      -d '{"mode":"test", "url": "https://gotranscript.com/tests/api/audio.mp3", "translate_from": "english", "translate_to": "german", "api_token": "login_to_see_token"}' \
      "https://gotranscript.com/api/v4/subtitles"
                            

    $curl = curl_init();

    curl_setopt_array($curl, [
      CURLOPT_URL => 'https://gotranscript.com/api/v4/subtitles',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => json_encode(
        [
            'mode' => 'test',
            'url' => 'https://gotranscript.com/tests/api/audio.mp3', // your file url
            'translate_from' => 'english',
            'translate_to' => 'german',
            'api_token' => 'login_to_see_token', // this is your API token
        ]
      ),
      CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
      ]
    ]);

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if ($err) {
      echo 'cURL Error #:' . $err;
    } else {
      echo $response;
    }
                            

    import requests

    endpoint = "https://gotranscript.com/api/v4/subtitles"

    json = {
        'mode': 'test',
        'url': 'https://gotranscript.com/tests/api/audio.mp3',
        'translate_from': 'english',
        'translate_to': 'german',
        'api_token': 'login_to_see_token',
    }

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

    response = requests.post(endpoint, json=json, headers=headers)
    parse(response)
                            

    const axios = require("axios");

    const assembly = axios.create({
      baseURL: "https://gotranscript.com",
      headers: {
        "Content-Type": "application/json"
      }
    });

    assembly
      .post("/api/v4/subtitles", {
        mode: "test",
        url: "https://gotranscript.com/tests/api/audio.mp3",
        translate_from: "english",
        translate_to: "german",
        api_token: "login_to_see_token"
      })
      .then(parseResponse)
      .catch(console.error);

Request parameters

Name Type Description
api_token String Your API token. Your current API token is: login_to_see_token.
mode String Can be one of the following: test, live. When set to test, file price is calculated but not charged from your wallet. This way you can test how much it will cost to make an order. When you want to make a real order, change test to live.
url String File url you want to make subtitles for.
translate_from String Language of file. List of available languages: english,albanian,arabic,armenian,azerbaijani,bengali,bosnian,bulgarian,catalan,chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,georgian,german,greek,hebrew,hungarian,indian,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-dari,persian-farsi,polish,portuguese,romanian,russian,serbian,shona,slovak,slovenian,somali,spanish,swahili,swedish,tajik,thai,turkish,turkmen,ukrainian,urdu,uzbek,vietnamese.
translate_to String Subtitle the given file to a given language. List of available languages: english,albanian,arabic,armenian,azerbaijani,bengali,bosnian,bulgarian,catalan,chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,georgian,german,greek,hebrew,hungarian,indian,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-dari,persian-farsi,polish,portuguese,romanian,russian,serbian,shona,slovak,slovenian,somali,spanish,swahili,swedish,tajik,thai,turkish,turkmen,ukrainian,urdu,uzbek,vietnamese.
comment String Here you can specify additional information for subtitles.
callback_url String When order is finished, you can specify url which will be used for callback.

Response body

Response will be in JSON format.


    {
       "mode":"live",
       "status":"success",
       "order_id":123, // order_id will be set only when wallet is charged (live mode)
       "order_total":12.34 // $12.34 dollars
       "seconds":0, // order duration in seconds
       "in_wallet":0, // how much money you have left in your GoTranscript wallet
       "delivery_estimate":"2022-11-30 14:02:44", // (UTC time)
    }

Callback

When file transcription is finished, POST request will be sent to your specified URL. It will contain JSON:


    {
        'mode' => 'live',
        'order_id' => 123,
        'subtitles_url' => 'https://gotranscript.com/api/v4/test-file/subtitles?api_token=login_to_see_token'
    }

To test how your server responds to request from gotranscript.com, click on the link below.

Send test response to your server

Other

Monitoring Orders

When api is used in live mode (not in testing), you can go to login. There you will see your orders and their statuses.

Updates to downloaded files

After an order is finished, some file are randomly selected to check their quality. When errors are found, they are fixed and one more request is sent to your specified API url. This request looks the same as original. It can be ignored if you already downloaded the file or you can redownload the file to get a version with fixed errors.

Different file types can return different callback data, please take a look at every API Callback object section.

Need help? Contact us: info@gotranscript.com

Get In Touch
+1 (831) 222-8398
Contact us form
Join us as a transcriber
About us
Blog
Privacy