Transcription API (v4)

Introduction

Using this transcription 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?

• 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.

When order will be finished, we will send POST request to your specified url.

Set your website url down below.

login to see form

Transcription Example

Send POST request to GoTranscript to order transcription.

<?php

$url = 'https://gotranscript.com/api/v4/transcriptions';
$data = [
    '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
];
echo curlPost($url, $data); // function definition can be found at the bottom of documentation 

• mode - 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 - file url you want to transcribe.
• language - language of file. Values: english, french, spanish, italian, lithuanian, filipino, russian, polish, shona, portuguese, dutch, german, turkish, macedonian, serbian, croatian, bosnian, arabic, chinese, japanese, greek, hebrew, indonesian, finnish, hungarian, swedish, korean, estonian, indian, romanian, urdu, norwegian, malay, danish, nepali, georgian, ukrainian, latvian, bengali, bulgarian, albanian, czech, vietnamese, catalan, somali, thai, swahili, slovak, slovenian, persian (farsi), azerbaijani, kurdish, uzbek, kyrgyz, tajik, persian (dari), pashto, armenian
• api_token - your api token.

You can pass additional parameters:

• comment - Here you can specify names of speakers or other information for transcribers.
• from - Start file transcription from this amount of seconds (integer).
• till - Finish file transcription at this amount of seconds (integer).
• text_format - values: clean_verbatim (default), full_verbatim
• timestamping - values: not_required (default), every_10_seconds, every_30_seconds, every_2_minutes, change_of_speaker
• turnaround_time - values: 12_hours, 1_days, 3_days, 5_days (default)
• number_of_speakers - values: 1_or_2 (default), 3_or_more
• callback_url - when order is finished, you can specify which url will be used for callback

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-06-29 09:44:32", // (UTC time)
} 

When file will be finished, POST request will be sent to your specified URL. It will contain this data:

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

When your server receives data, it must output ok. If it will not output ok, we will send this request again every hour up to 10 times.

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 Example

Send POST request to GoTranscript to order translation.

<?php

$url = 'https://gotranscript.com/api/v4/translations';
$data = [
    '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
];
echo curlPost($url, $data); // function definition can be found at the bottom of documentation 

• mode - 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 - file url you want to transcribe.
• translate_from - translate from language. Values: english, french, italian, spanish, lithuanian, romanian, german, arabic, japanese, chinese (traditional), russian, dutch, danish, korean, norwegian, turkish, indian (hindi), indian (gujarati), filipino, polish, ukrainian, greek, chinese (simplified), hungarian, bengali, swedish, hebrew, serbian, czech, nepali, indonesian, catalan, somali, malay, thai, finnish, bosnian, swahili, vietnamese, albanian, bulgarian, latvian, croatian, slovenian, slovak, macedonian, urdu, estonian, persian (farsi), kurdish, georgian, azerbaijani, portuguese (brazil), portuguese (portugal), french (canadian), indian (tamil) , armenian
• translate_to - translate to language. Values: english, french, italian, spanish, lithuanian, romanian, german, arabic, japanese, chinese (traditional), russian, dutch, danish, korean, norwegian, turkish, indian (hindi), indian (gujarati), filipino, polish, ukrainian, greek, chinese (simplified), hungarian, bengali, swedish, hebrew, serbian, czech, nepali, indonesian, catalan, somali, malay, thai, finnish, bosnian, swahili, vietnamese, albanian, bulgarian, latvian, croatian, slovenian, slovak, macedonian, urdu, estonian, persian (farsi), kurdish, georgian, azerbaijani, portuguese (brazil), portuguese (portugal), french (canadian), indian (tamil) , armenian
• api_token - your api token.

You can pass additional parameters:

• comment - Here you can specify additional information for translators.
• callback_url - when order is finished, you can specify which url will be used for callback

Response will be in JSON format. You will get order_id and order_total.

{
   "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-06-29 09:44:32", // (UTC time)
} 

When file will be finished, POST request will be sent to your specified URL. It will contain this data:

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

When your server receives data, it must output ok. If it will not output ok, we will send this request again every hour up to 10 times.

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.

<?php

$url = 'https://gotranscript.com/api/v4/captions';
$data = [
    '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
];
echo curlPost($url, $data); // function definition can be found at the bottom of documentation 

• mode - 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 - file url you want to transcribe.
• language - language of file. Values: english, french, spanish, italian, lithuanian, filipino, russian, polish, shona, portuguese, dutch, german, turkish, macedonian, serbian, croatian, bosnian, arabic, chinese, japanese, greek, hebrew, indonesian, finnish, hungarian, swedish, korean, estonian, indian, romanian, urdu, norwegian, malay, danish, nepali, georgian, ukrainian, latvian, bengali, bulgarian, albanian, czech, vietnamese, catalan, somali, thai, swahili, slovak, slovenian, persian (farsi), azerbaijani, kurdish, uzbek, kyrgyz, tajik, persian (dari), pashto, armenian
• api_token - your api token.

You can pass additional parameters:

• comment - Here you can specify names of speakers or other information for subtitlers.
• from - Start file transcription from this amount of seconds (integer).
• till - Finish file transcription at this amount of seconds (integer).
• text_format - values: clean_verbatim (default), full_verbatim
• timestamping - values: not_required (default), every_10_seconds, every_30_seconds, every_2_minutes, change_of_speaker
• turnaround_time - values: 12_hours, 1_days, 3_days, 5_days (default)
• number_of_speakers - values: 1_or_2 (default), 3_or_more
• callback_url - when order is finished, you can specify which url will be used for callback

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-06-29 09:44:32", // (UTC time)
} 

When file will be finished, POST request will be sent to your specified URL. It will contain this data:

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

When your server receives data, it must output ok. If it will not output ok, we will send this request again every hour up to 10 times.

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.

<?php

$url = 'https://gotranscript.com/api/v4/subtitles';
$data = [
    '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
];
echo curlPost($url, $data); // function definition can be found at the bottom of documentation 

• mode - 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 - file url you want to transcribe.
• translate_from - translate from language. Values: english, french, italian, spanish, lithuanian, romanian, german, arabic, japanese, chinese (traditional), russian, dutch, danish, korean, norwegian, turkish, indian (hindi), indian (gujarati), filipino, polish, ukrainian, greek, chinese (simplified), hungarian, bengali, swedish, hebrew, serbian, czech, nepali, indonesian, catalan, somali, malay, thai, finnish, bosnian, swahili, vietnamese, albanian, bulgarian, latvian, croatian, slovenian, slovak, macedonian, urdu, estonian, persian (farsi), kurdish, georgian, azerbaijani, portuguese (brazil), portuguese (portugal), french (canadian), indian (tamil) , armenian
• translate_to - translate to language. Values: english, french, italian, spanish, lithuanian, romanian, german, arabic, japanese, chinese (traditional), russian, dutch, danish, korean, norwegian, turkish, indian (hindi), indian (gujarati), filipino, polish, ukrainian, greek, chinese (simplified), hungarian, bengali, swedish, hebrew, serbian, czech, nepali, indonesian, catalan, somali, malay, thai, finnish, bosnian, swahili, vietnamese, albanian, bulgarian, latvian, croatian, slovenian, slovak, macedonian, urdu, estonian, persian (farsi), kurdish, georgian, azerbaijani, portuguese (brazil), portuguese (portugal), french (canadian), indian (tamil) , armenian
• api_token - your api token.

You can pass additional parameters:

• comment - Here you can specify additional information for subtitles.
• callback_url - when order is finished, you can specify which url will be used for callback

Response will be in JSON format. You will get order_id and order_total.

{
   "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-06-29 09:44:32", // (UTC time)
} 

When file will be finished, POST request will be sent to your specified URL. It will contain this data:

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

When your server receives data, it must output ok. If it will not output ok, we will send this request again every hour up to 10 times.

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

Send test response to your server

Other

curlPost()

This is curlPost() function that sends POST request using CURL. It is used in examples.

function curlPost($url, array $data) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    $response = curl_exec($ch);
    if ($response === false) {
        throw new \Exception(curl_error($ch));
    }
    curl_close($ch);

    return $response;
}             

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.