Aditu files API

Credit info

Functions to obtain user account's credit info, such as transcription time or disk space.

URL

https://api.aditu.eus

Methods

Check user time information.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>"
}
Response example 

{
	"user_time": 36000 # in seconds, 10 hours
}

Check user server space information.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>"
}
Response example 

{
	"server_space": 5368709120, # in bytes, 5GB
	"used_server_space": 2254857830 # 2.1GB
}

Transcribe/Subtitle file

Functions to upload a file for transcribing/subtitling.
Audio (.wav, .mp3...) and video (.mp4, .webm...) files are accepted. Available languages are Basque, Spanish and Basque/Spanish bilingual.
File is kept in server and further operations (translate, edit, export, delete...) can be demanded through its ID.

URL

https://api.aditu.eus

Methods

Upload a file for transcribing/subtitling.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>",
	"language" : "eu" | "es" | "eu-es",
	"channel" : 0 (left) | 1 (right) | 2 (stereo, default),
	"speaker_group" : "<SPEAKER_GROUP_ID>" (optional),
	"file" : <YOUR_FILE>
}
Response example 

{
	"task_id" : "6dc0ce4d-08c5-4754-8ecc-5385e489684e",
}

Check progress of a given transcription task.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>",
	"task_id" : "6dc0ce4d-08c5-4754-8ecc-5385e489684e"
}
Response example Task is running 

{
	"finished": False,
	"error": False,
	"percentage": "75",
	"message": "Running transcription", # Just an example
}
Task finished with errors. 

{
	"finished": True,
	"error": True,
	"file_id": <FILE_ID>, # File id (needed for deleting)
	"message": "There was an error", # Just an example
}
Task finished without errors. 

{
	"finished": True,
	"error": False,
	"file_id": <FILE_ID>, # File id (needed for editing, deleting, translating and obtaining SRT, VTT, TXT, JSON... exports)
	"execution_time": 67.25 # Time to transcribe file in seconds
}

Translate file

Functions to translate a file previously transcribed.
The language to translate to can be any of Basque, Spanish, French, English, Catalan or Galician, plus inverse bilingual for bilingual transcriptions.
Source language for translation can be the original language or any translation previously done.
For best results, the file should have been previously edited and corrected. Ordering a translation to a language that was already translated deletes the previous one, even if it was corrected.

URL

https://api.aditu.eus

Methods

Translate a file.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>",
	"file_id" : <FILE_ID>,
	"from_language" : "eu" | "es" | "fr" | "ca" | "gl" | "en" | "eu-es",
	"to_language" : "eu" | "es" | "fr" | "ca" | "gl" | "en" | "eues_inv" (only from eu-es)
}
Response example 

{
	"task_id" : "6dc0ce4d-08c5-4754-8ecc-5385e489684e",
}

Check progress of a given translation task.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>",
	"task_id" : "6dc0ce4d-08c5-4754-8ecc-5385e489684e"
}
Response example Info not ready yet (allow up to 5 retries, with some seconds in between) 

{
	"error": "ERROR",
	"message": "Server error", # Just an example
}
Task is running 

{
	"finished": False,
	"error": False,
	"percentage": "75",
	"message": "Running translation", # Just an example
}
Task finished with errors. 

{
	"finished": True,
	"error": True,
	"message": "There was an error", # Just an example
}
Task finished without errors. 

{
	"finished": True,
	"error": False,
	"words": 369,
	"execution_time": 3.39 #Time to translate file in seconds
}

File edition interface

Function to open an interface to manually edit any transcription or translation previously made.

URL

https://aditu.eus

Methods

.

Returns an HTML page, intended to be opened in a browser tab, for editing a transcription previously made or one its translations if a language is passed. It can be passed a URL to notify that it was saved in the editor, with a parameter to pass as external id of the file.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>",
	"file_id" : "<FILE_ID>",
	"language" : "eu" | "es" | "fr" | "ca" | "gl" | "en" | "eu-es" | "eues_inv", # Optional, for editing a translation instead of the original transcription
	"video_url" : "", # URL of video to show on edition page
	"save_notify_url" : "", # URL to notify that file was saved in the editor (optional)
	"nid" : "" # identifier to pass to save_notify_url (optional)
}
Response example 

{
	<html>
		<head>
			...
		</head>
		<body>
			...
		</body>
	</html>
}

Export file

Function to export a file's transcription or one of its translations (previously done and optionally edited) to one of various export formats.
Posible formats:
Some export formats (SRT, VTT and DOCX) can be asked to have speaker info in them, of various types:

URL

https://api.aditu.eus

Methods

Get an export, in various formats and options, of a given transcription or translation previously sent and already finished.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>",
	"file_id" : <FILE_ID>,
	"language" : "eu" | "es" | "fr" | "ca" | "gl" | "en" | "eues_inv" (only from eu-es), # Optional, will export translation instead of original
	"format" : "SRT" | "VTT" | "STL" | "DOCX" | "MIN" | "TXT" | "WORDS",
	"speaker_info": "none" | "hyphens" | "colors" | "names" # Optional
}
Response example SRT file with no speaker info 

1
00:00:00,380 --> 00:00:02,270
Zirkulazio-aparatua.

2
00:00:02,280 --> 00:00:07,820
Hainbat aldiz entzun duzu elkarren
artean loturik eta koordinaturik

3
00:00:07,830 --> 00:00:10,460
diharduten hainbat
aparatuk edo

4
00:00:10,470 --> 00:00:13,860
sistemak osatzen dutela
gure organismoa.

...
SRT file with speaker names 

1
00:00:00,380 --> 00:00:02,270
JOSU: Zirkulazio-aparatua.

2
00:00:02,280 --> 00:00:06,590
MIKEL: Hainbat aldiz entzun duzu
elkarren artean loturik eta

3
00:00:06,600 --> 00:00:09,420
koordinaturik
diharduten hainbat

4
00:00:09,430 --> 00:00:13,850
aparatuk edo sistemak osatzen
dutela gure organismoa.

...
Transcription in TXT 

Zirkulazio-aparatua. Hainbat aldiz entzun duzu elkarren artean loturik eta koordinaturik diharduten hainbat aparatuk edo sistemak osatzen dutela gure organismoa. ...
Minutes in DOCX 

ZIRKULAZIO_APARATUA.mp4

[00:00:00.380] - JOSU
Zirkulazio-aparatua.
[00:00:02.279] - MIKEL
Hainbat aldiz entzun duzu elkarren artean loturik eta koordinaturik diharduten hainbat aparatuk edo sistemak osatzen dutela gure organismoa. ...
Words in JSON 

{
  "words": [
    {
      "utterance": "ZIRKULAZIO_APARATUA-0000230-0002450",
      "word": "Zirkulazio-",
      "confidence": "1.00",
      "start": "0.38",
      "duration": "1.04",
      "speaker": "JOSU"
    },
    {
      "utterance": "ZIRKULAZIO_APARATUA-0000230-0002450",
      "word": "aparatua.",
      "confidence": "1.00",
      "start": "1.42",
      "duration": "0.85",
      "speaker": "JOSU"
    },
    {
      "utterance": "ZIRKULAZIO_APARATUA-0003970-0010590",
      "word": "Hainbat",
      "confidence": "1.00",
      "start": "2.26",
      "duration": "0.66",
      "speaker": "MIKEL"
    },
    {
      "utterance": "ZIRKULAZIO_APARATUA-0003970-0010590",
      "word": "aldiz",
      "confidence": "1.00",
      "start": "2.92",
      "duration": "0.47",
      "speaker": "MIKEL"
    },
    {
      "utterance": "ZIRKULAZIO_APARATUA-0003970-0010590",
      "word": "entzun",
      "confidence": "1.00",
      "start": "3.39",
      "duration": "0.57",
      "speaker": "MIKEL"
    },
    {
      "utterance": "ZIRKULAZIO_APARATUA-0003970-0010590",
      "word": "duzu",
      "confidence": "1.00",
      "start": "3.96",
      "duration": "0.38",
      "speaker": "MIKEL"
    },

...

}

Delete file

Function to delete a file. Recommended to call after finishing all needed operations on a file (transcribe, edit, translate, export...) or if error when transcribing.

URL

https://api.aditu.eus

Methods

Delete a file.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>",
	"file_id" : <FILE_ID>
}
Response example Error when deleting. 

{
	"error": True,
	"message": "There was an error", # Just an example
}
Delete successful. 

{
	"error": False
}

Speaker group id

Function to get the speaker group id. Before you send a file to transcribe, in the case you want to apply speaker verification, you need to specify the speaker group id. .

URL

https://api.aditu.eus

Methods

Get the speaker group id from name.

Request example 

{
	"api_id" : "<YOUR_API_ID>",
	"api_key" : "<YOUR_API_KEY>",
	"group_name" : "<SPEAKER_GROUP_NAME>"
}
Response example Error. 

{
	"error": True,
	"message": "There was an error", # Just an example
}
Successful. 

{
	"speaker_group_id": "<SPEAKER_GROUP_ID>",
	"error": False
}

Client software examples

Credit info, transcription and export

Python

Python script that calls the API with the contents of an audio or video file and retrieves the results: https://api.aditu.eus/static/api_client.py.

Shell script

Shell script that calls the API with the contents of an audio or video file and retrieves the results: https://api.aditu.eus/static/api_client.sh.

Translation

Python

Python script that calls the API for translating a file: https://api.aditu.eus/static/api_client_translate.py.

Edition

HTML

HTML code that, when opened in a browser, will open Aditu's interface to edit the transcription or translation specified in the variables of the code: https://api.aditu.eus/static/post_open_external.html.

Deletion

Python

Python script that calls the API to delete a file: https://api.aditu.eus/static/api_client_delete.py.

Transcription with speaker identification

Python

Python script that calls the API to transcribe a file with speaker identification: https://api.aditu.eus/static/api_client_speaker.py.