Transcription API
Fully Automated, 100% Human Transcription & Captioning

GoTranscript offers cloud-native API solutions for quick, continuous transcription and captioning, ensuring precision in every output.

Download GoTranscript Presentation 2023
graphic
Download GoTranscript Presentation 2023

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 respond with the string ok. If the response is not ok, the request will be retried up to a maximum of 10 attempts, with random time intervals between each attempt.

Transcription

Send POST request to GoTranscript to order transcription.

Request example

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,arabic,bosnian,catalan,chinese-simplified,chinese-traditional,croatian,dutch,filipino,french,german,hebrew,indonesian,italian,japanese,korean,lithuanian,persian-dari,persian-farsi,portuguese,romanian,russian,serbian,spanish,swahili,swedish,turkish,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).
The following languages supports only 5_days value: bosnian,catalan,croatian,filipino,french,hebrew,indonesian,lithuanian,persian-dari,persian-farsi,portuguese,romanian,russian,serbian,swahili,swedish,turkish,vietnamese.
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":"2024-03-19 07:52:03", // (UTC time)
    }
                    

Callback

When file transcription is finished, POST request will be sent to your specified URL. This request will include a payload data in multipart/form-data format with the following values:


    {
        '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 url. You can also get transcription in different formats by adding format query parameter to the url with available values: 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

AI Transcription & Captions

This API transcribes audio into your chosen language and provides both the transcription and caption files.
Note: you can select a different language for translation. For instance, if you choose German for an English file, both the transcription and captions will be in German.

Request example

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 Audio url to transcribe.
language String Language of audio file. List of available languages: english,arabic,catalan,dutch,french,german,hebrew,indonesian,italian,japanese,korean,lithuanian,portuguese,romanian,russian,serbian,spanish,swedish,turkish.
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":"2024-03-19 07:52:03", // (UTC time)
    }
	

Callback

If a callback_url parameter is specified in the order request, then POST request will be sent to your specified URL when the state of the order changes. This request will include a payload data in multipart/form-data format with the following values:

Name Type Description
mode String Can be one of the following: test, live.
order_id Integer Order ID.
status String Can be one of the following: finished, refunded. A refund will be provided to your wallet if we are unable to transcribe the file.
language String Language of transcription.
transcription_url String URL of the completed transcription or an empty string if the status parameter value is not finished.
captions_url String URL of the completed captions or an empty string if the status parameter value is not finished.

Transcription file format: transcription_url returns .docx document url. You can also get transcription in different formats by adding format query parameter to the url with available values: docx, doc, pdf, text, html or json.
Example: https://gotranscript.com/api/v4/test-file/automatic_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

Transcription Proofreading

Get your AI transcription proofread. Upload your audio file and AI transcription text, and we'll return the corrected text.
For low-quality AI transcriptions, we'll refund your money to the GoTranscript wallet. You can then decide whether to order a human transcription.

Request example

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.
audio_url String Audio file url you want to transcribe.
transcription_url String Audio transcription file url you want to correct.
language String Language of file. List of available languages: english,arabic,bosnian,catalan,chinese-simplified,chinese-traditional,croatian,dutch,filipino,french,german,hebrew,indonesian,italian,japanese,korean,lithuanian,persian-dari,persian-farsi,portuguese,romanian,russian,serbian,spanish,swahili,swedish,turkish,vietnamese.
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).
The following languages supports only 5_days value: bosnian,catalan,croatian,filipino,french,hebrew,indonesian,lithuanian,persian-dari,persian-farsi,portuguese,romanian,russian,serbian,swahili,swedish,turkish,vietnamese.
comment String Here you can specify names of speakers or other information for transcribers.
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":"2024-03-19 07:52:03", // (UTC time)
    }
                    

Callback

If a callback_url parameter is specified in the order request, then POST request will be sent to your specified URL when the state of the order changes. This request will include a payload data in multipart/form-data format with the following values:

Name Type Description
mode String Can be one of the following: test, live.
order_id Integer Order ID.
status String Can be one of the following: finished, refunded. Refund will be given if your supplied AI transcription quality is too low.
proofread_transcription_url String URL of the completed transcription or an empty string if the status parameter value is not finished.

Transcription file format. transcription_url returns .docx document url. 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/transcription_proofreading?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

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,azerbaijani,bengali,bosnian,bulgarian,catalan,simplified-chinese,traditional-chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,french-canadian,georgian,german,greek,hebrew,hungarian,indian-gujarati,indian-hindi,indian-tamil,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-farsi,polish,portuguese-brazil,portuguese-portugal,romanian,russian,serbian,slovak,slovenian,somali,spanish-latin,spanish,swahili,swedish,thai,turkish,ukrainian,urdu,vietnamese.
translate_to String Translate the given file text to a given language. List of available languages: english,albanian,arabic,azerbaijani,bengali,bosnian,bulgarian,catalan,simplified-chinese,traditional-chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,french-canadian,georgian,german,greek,hebrew,hungarian,indian-gujarati,indian-hindi,indian-tamil,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-farsi,polish,portuguese-brazil,portuguese-portugal,romanian,russian,serbian,slovak,slovenian,somali,spanish-latin,spanish,swahili,swedish,thai,turkish,ukrainian,urdu,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":"2024-03-19 07:52:03", // (UTC time)
    }
                    

Callback

When file transcription is finished, POST request will be sent to your specified URL. This request will include a payload data in multipart/form-data format with the following values:


    {
        '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

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,arabic,bosnian,catalan,chinese-simplified,chinese-traditional,croatian,dutch,filipino,french,german,hebrew,indonesian,italian,japanese,korean,lithuanian,persian-dari,persian-farsi,portuguese,romanian,russian,serbian,spanish,swahili,swedish,turkish,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).
The following languages supports only 5_days value: bosnian,catalan,croatian,filipino,french,hebrew,indonesian,lithuanian,persian-dari,persian-farsi,portuguese,romanian,russian,serbian,swahili,swedish,turkish,vietnamese.
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":"2024-03-19 07:52:03", // (UTC time)
    }
                    

Callback

When file transcription is finished, POST request will be sent to your specified URL. This request will include a payload data in multipart/form-data format with the following values:


    {
        '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

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,azerbaijani,bengali,bosnian,bulgarian,catalan,simplified-chinese,traditional-chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,french-canadian,georgian,german,greek,hebrew,hungarian,indian-gujarati,indian-hindi,indian-tamil,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-farsi,polish,portuguese-brazil,portuguese-portugal,romanian,russian,serbian,slovak,slovenian,somali,spanish-latin,spanish,swahili,swedish,thai,turkish,ukrainian,urdu,vietnamese.
translate_to String Subtitle the given file to a given language. List of available languages: english,albanian,arabic,azerbaijani,bengali,bosnian,bulgarian,catalan,simplified-chinese,traditional-chinese,croatian,czech,danish,dutch,estonian,filipino,finnish,french,french-canadian,georgian,german,greek,hebrew,hungarian,indian-gujarati,indian-hindi,indian-tamil,indonesian,italian,japanese,korean,kurdish,kyrgyz,latvian,lithuanian,macedonian,malay,nepali,norwegian,pashto,persian-farsi,polish,portuguese-brazil,portuguese-portugal,romanian,russian,serbian,slovak,slovenian,somali,spanish-latin,spanish,swahili,swedish,thai,turkish,ukrainian,urdu,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":"2024-03-19 07:52:03", // (UTC time)
    }
                    

Callback

When file transcription is finished, POST request will be sent to your specified URL. This request will include a payload data in multipart/form-data format with the following values:


    {
        '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

Get list of Orders

Send GET request to GoTranscript to get list of orders.

Request example

Query 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, the API will return a list of the sample orders for testing purposes.
cursor String This field is used to paginate results. The cursor parameter will be automatically filled in the next_page_url.

Response body

Name Type Description
id Integer Order ID.
type String Can be one of the following: transcriptions, captions, translations, subtitles.
price Float Amount of money paid for order in USD.
paid_at String or null The date and time the order was paid in UTC time. Null value if order is not paid yet.
delivery_estimate String The date and time the order should be done in UTC time. Null value if order is not paid yet.
finished_at String or null The date and time the order was finished in UTC time. Null value if order is not finished yet.
comment String User comment passed as an argument.
seconds Integer Total duration of the order's audio files (in seconds).
words Integer Total number of words in the order's documents.
translate_from String Translate from the given file text language. Value passed as an argument with translation or subtitle order.
translate_to String Translate the given file text to a given language. Value passed as an argument with translation or subtitles order.
language String Language of file. Value passed via language argument. Value passed as an argument with transcription or captions order.
text_format String Value passed as an argument with transcription or captions order.
timestamping String Value passed as an argument with transcription or captions order.
turnaround_time String Value passed as an argument with transcription or captions order.
number_of_speakers String Value passed as an argument with transcription or captions order.
transcription_url String Transcription file url, will be served after order is finished.
captions_url String Captions file url, will be served after order is finished.
translation_url String Translations file url, will be served after order is finished.
subtitles_url String Subtitles file url, will be served after order is finished.

Response will be in JSON format.


    {
      "orders": [
        {
          "id": 1,
          "type": "captions",
          "price": 1.21,
          "paid_at": "2022-11-20 21:00:00",
          "delivery_estimate": "2022-11-20 21:00:00",
          "finished_at": "2022-11-20 21:00:00",
          "comment": "Speaker names: John and Dave",
          "seconds": 1000,
          "words": 0,
          "language": "english",
          "text_format": "clean_verbatim",
          "timestamping": "not_required",
          "turnaround_time": "days_3",
          "number_of_speakers": "1_or_2",
          "captions_url": "https://gotranscript.com/api/v4/orders/1/captions?api_token=login_to_see_token"
        },
        ...
      ],
      "next_page_url": https://gotranscript.com/api/v4/orders?mode=test&api_token=login_to_see_token&cursor=string
    }
    

Get Order by ID

Send GET request to GoTranscript to get order.

Request example

Query 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, the API will return one of the sample orders for testing purposes.

Response body

Order response description can be found here.

Response will be in JSON format.


    {
      "data": {
        "id": 1,
        "type": "captions",
        "price": 1.21,
        "paid_at": "2022-11-20 21:00:00",
        "delivery_estimate": "2022-11-20 21:00:00",
        "finished_at": "2022-11-20 21:00:00",
        "comment": "Speaker names: John and Dave",
        "seconds": 1000,
        "words": 0,
        "language": "english",
        "text_format": "clean_verbatim",
        "timestamping": "not_required",
        "turnaround_time": "days_3",
        "number_of_speakers": "1_or_2",
        "captions_url": "https://gotranscript.com/api/v4/orders/1/captions?api_token=login_to_see_token"
        ]
      }
    }
    

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