Transcription API Documentation (v3)

There is newer API version

Introduction

Using this API you can submit files for:

  • transcription (audio/video files)
  • subtitling (audio/video files)
  • translation (.doc, .docx...)

How it works?

server communication
  • 1. Your server sends url of file
  • 2. Price is calculated and returned to you
  • 3. Your server makes payment from your wallet
  • 4. When file is finished, we will ping your server's url that order has been finished

Getting ready

API token

All requests sent to gotranscript.com API must have token.
Example: https://gotranscript.com/api/v3/....?api_token=API_TOKEN

Callback url

We will send POST request to your website url when order will be finished.

Set your website url down below.

login to see form

Code

All code examples will be in PHP. And for simplicity we will use curlGet() and curlPost() functions.

<?php

function curlGet($url) {
    return curl($url);
}

function curlPost($url, array $data) {
    return curl($url, $data);
}

function curl($url, array $data = null) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    if ($data) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    }
    $response = curl_exec($ch);
    curl_close($ch);

    return $response;
} 

1 step. Add file

Send your file url and parameters how file should be processed to gotranscript.com. You can choose whether you want to transcribe, subtitle or translate file.

Below will be 2 examples: for transcription/subtitling and for translation.

1.1 step. Add file (for transcription/subtitling)

<?php

$url = 'https://gotranscript.com/api/v3/files/add?api_token=API_TOKEN';
$data = [
    'type' => 'transcription', // you can change this parameter to "subtitling"
    'url' => 'http://your-url.com/your-file.mp3',
    'comment' => '[optional] Instructions for transcribers', // optional

    'from' => 0, // optional
    'till' => 120, // optional - if set, file will we transcribed from 00:00:00 till 00:02:00 (2 minutes)
    'language' => 'english',
    'text_format' => 'clean_verbatim',
    'timestamping' => 'not_required',
    'turnaround_time' => '5_days',
    'number_of_speakers' => '1_or_2',
];

echo curlPost($url, $data); 
  • type - type of work that we will do. Values: transcription, subtitling, translation
  • url - file you want to transcribe/subtitle/translate. Url must be available until we ping your server that order is done!
  • comment - Optional. Here you can specify names of spekers or other information. Also you can leave it empty.
  • from - Optional. Start file transcription from this amount of seconds.
  • till - Optional. Finish file transcription at this amount of seconds.
  • language - values: english, french, spanish, italian, lithuanian, filipino, russian, polish, portuguese, dutch, german, turkish, serbian, croatian, bosnian, arabic, chinese, japanese, greek, hebrew, indonesian, finnish, hungarian, swedish, korean, estonian, indian, romanian, norwegian, malay, luxembourgish, danish, icelandic, nepali, ukrainian, latvian
  • text_format - values: clean_verbatim, full_verbatim
  • timestamping - values: not_required, every_2_minutes, change_of_speaker
  • turnaround_time - values: 1_days, 2_days, 3_days, 4_days, 5_days
  • number_of_speakers - values: 1_or_2, 3_or_more

1.2 step. Add file (for translation)

This request is similar to transcription/subtitling request, but it needs less parameters.

<?php

$url = 'https://gotranscript.com/api/v3/files/add?api_token=API_TOKEN';
$data = [
    'type' => 'translation',
    'url' => 'http://your-url.com/your-file.doc',
    'comment' => 'Instructions for translators [optional]',

    'translate_from' => 'english',
    'translate_to' => 'german',
];

echo curlPost($url, $data); 
  • type - type of work that we will do. Values: transcription, subtitling, translation
  • url - file you want to transcribe/subtitle/translate.
  • comment - optional. Here you can specify some information if you need.
  • translate_from - translate from language. Values: english, french, italian, spanish, lithuanian, romanian, portuguese, german, arabic, japanese, traditional chinese, russian, dutch, danish, korean, norwegian, turkish, indian (hindi), indian (gujarati), filipino, polish, ukraine, greek, simplified chinese, hungarian
  • translate_to - translate to language. Values: english, french, italian, spanish, lithuanian, romanian, portuguese, german, arabic, japanese, traditional chinese, russian, dutch, danish, korean, norwegian, turkish, indian (hindi), indian (gujarati), filipino, polish, ukraine, greek, simplified chinese, hungarian

2 step. Price

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

{
   "mode":"test",
   "status":"success",
   "data":{
      "order_id":777,
      "order_total":77.77 // $77.77 dollars
   }
} 

If you forgot to change API_TOKEN or made other mistake, error will look like this:

{
   "mode":"live",
   "status":"error",
   "error":"Wrong api token"
} 

3 step. Payment

Make payment from your wallet. Don't forget to change ORDER_ID.

<?php

$url = 'https://gotranscript.com/api/v3/orders/ORDER_ID/pay?api_token=API_TOKEN';

echo curlGet($url); 

Response:

{
   "mode":"test",
   "status":"success",
   "data":null
} 

4 step. Transcription/subtitles/translation download url

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

$data = [
    'mode' => 'live',
    'status' => 'success',
    'order_id' => 777,
    'transcription_url' => 'https://gotranscript.com/api/v3/test/test-file/1?api_token=test', // present only when "type" is "transcription" or "subtitling"
    'subtitles_url' => 'https://gotranscript.com/api/v3/test/test-file/2?api_token=test', // present only when "type" is "subtitling"
    'translation_url' => 'https://gotranscript.com/api/v3/test/test-file/3?api_token=test', // present only when "type" is "translation"
];

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.

API_TOKEN value will be set automatically on returned url's.

Transcription file format. "'transcription_url" returns .docx document. You can also get plain text by adding to 'transcription_url' &format=text or get html by adding &format=html.
Example: https://gotranscript.com/api/v3/test/test-file/1?api_token=test&format=html. Works only in live mode.

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

Test request to your server (type: transcription)
Test request to your server (type: subtitling)
Test request to your server (type: translation)

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.

Discount

All orders made through API receive 20% discount.

Need help? Contact us: info@gotranscript.com