Welcome to the Maestra API

Maestra API Version: 1.0.1
Base URL:

companion.maestrasuite.com

If you have any questions, please contact to us at support@maestra.ai

Import

POST /api/uploadFile

Initiates a new file upload to Maestra.


Parameters


Content-Type application/json
apiKey string (header)
requestObject (body)
UploadRequest
Example Value
{
  "fileUrl": "https://random.publicfilepath.mp4",
  "fileName": "Sample file name",
  "mediaType": "video/mp4",
  "audioLanguage": "en-US",
  "speakerCount": 2,
  "dictionaryKey": "default",
  "channelId": "-MGsa3fPlGmTUd52mH64",
  "folderPath": "root/-MbixMpLJ05xgjvwNnPm/-McCIYUrFqeXQGrEqQpR",
  "operationType": "voiceover", #transcription, caption, voiceover
  "skipTranscription": false, #true, false
  "targetLanguages": {
    "french": true,
    "spanish": true
  }
}

Responses


200

Item created.

Return Type
Example Value
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
  "message": "Import job has been started."
}
400

Invalid url, invalid body.

401

Unauthorized


POST /api/importSubtitle

Initiates a new subtitle file upload.

This can potentially be a destructive operation, the sentences in the current file will be replaced with the imported subtitles and all the previous edits will be lost.


Parameters


Content-Type application/json
apiKey string (header)
requestObject (body)
ImportSubtitleRequest
Example Value
{
  "fileId": "-MGsa3fPlGmTUd52mH64",
  "operationType": "voiceover", #caption, voiceover
  "targetLanguage": "english",
  "subtitleType": "srt",
  "subtitleUrl": "https://random.publicsubtitlefilepath.srt"
}

Responses


200

Item created.

Return Type
Example Value
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
  "message": "Import Subtitle request has been sent."
}
400

Invalid url, invalid body.

401

Unauthorized


Translate

POST /api/translate

Translates an existing file in the system.


Parameters


Content-Type application/json
apiKey string (header)
requestObject (body)
TranslateRequest
Example Value
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
  "operationType": "voiceover", #transcription, caption, voiceover
  "targetLanguages": {
    "french": true,
    "spanish": true
  }
}

Responses


200

Translation created.

Return Type
Example Value
{
  "message": "Translation generated."
}
400

Invalid url, invalid body.

401

Unauthorized

404

Not found


Voiceover

POST /api/generateVoiceover

Generates voiceover for a specific language.


Parameters


Content-Type application/json
apiKey string (header)
requestObject (body)
VoiceoverGenerateRequest
Example Value
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
  "targetLanguages": {
    "french": true,
    "spanish": true
  }
}

Responses


200

Voiceover synthesisis started.

Return Type
Example Value
{
  "message": "Voiceover synthesisis started."
}
400

Invalid url, invalid body.

401

Unauthorized

404

Not found


POST /api/exportVoiceover

Exports voiceover for a specific file ID and language.


Parameters


Content-Type application/json
apiKey string (header)
requestObject (body)
VoiceoverExportRequest
Example Value
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
  "targetLanguages": {
    "german": true,
    "english": true
  }
}

Responses


200

Voiceover export started.

Return Type
Example Value
{
  "exportLinks": {
    "german": "https://storage.googleapis.com/maestro-218920.appspot.com/jdS8IbKPMNY2Bj6zjoO0nY0dTLs1/voiceoverOutput/german/-NZ6YfPR9TmhJBKaIisa.wav?GoogleAccessId=starting-account-3h04bluhbwaf%40maestro-218920.iam.gserviceaccount.com&Expires=1694665757&Signature=PMlHkTch2%2FTdYplL6xfvW78FN641B%2FLlLQsKWYmgugKQvhrV98Gp6wgQ%2FcgicNbM1Wbr2nBoOF0ZW9PkR6BwYnul5XaxrbodAYS59k524bQbrNuvIV4aOa1ymFBWLWbNrcPBiTypkKRK6rDz7vAVeorQLVQ7S%2F4C71uvXfEY%2BGFqZJTsTt23yAscYVnDnOq%2Bi%2BU2QDUrOa%2BE%2FEVeliq8h9X9fUv0Y2e%2FlBUDgqv6Nqhe9T%2F5rR1MlxpzyRdl%2FeVQvVNrQz3s9H1L0EQHqrc3PfpgpKkEcGv2mVz%2BOjrasNNAPTwm1ISDfTE0PbujTuroW8ooXryhXReWdUROwgLBFg%3D%3D",
    "english": "https://storage.googleapis.com/maestro-218920.appspot.com/jdS8IbKPMNY2Bj6zjoO0nY0dTLs1/voiceoverOutput/english/-NZ6YfPR9TmhJBKaIisa.wav?GoogleAccessId=starting-account-3h04bluhbwaf%40maestro-218920.iam.gserviceaccount.com&Expires=1694665757&Signature=rCZZjfM%2FVx7qDAf76z1XHe%2F7ghHCvluye%2FgJGvaBgyFM5NH1i0IQhC6t%2FlYj%2FJNQgy4%2BWEeRwRLk%2F%2F2es6df4Io2SVCN2h%2FpphJpOPF3snC2xgKuA5%2BEIXrw%2F1c9h9uqVqEaVq0wA6YtUMJtT2UtIiaRi98TBFJKT5eFiGJ%2BSU8j1RHzCJS8sZBGZXE4SFjbNVGVHgkzBvFMHsvzTyZnRZo3PmbnwVwAB8RXZ10eWmIlARYURfFf9wOQ5%2Fs%2Fm8a6sRMOicx15YOETJ6p1N9yVz2KeWd9RbPiNw0ITYrMnzekdLti5w5Q%2FO0RqaDcTHwHw0pKvr52QzQq%2FK4Xq9OpKA%3D%3D"
  }
}
400

Invalid url, invalid body.

401

Unauthorized

404

Not found


File System

GET /api/getFiles

Grabs the file list with key id and basic information.


Parameters


apiKey string (header)
fileId (optional) string (query)

optional parameter to get a single file instead of the file list

operationType (optional) string (query)

transcript, caption, voiceover

Responses


200

Search results matching criteria.

Return Type
Example Value
{
    "edited": 1569004761852,
    "created": 1569004761852,
    "duration": 12.399438,
    "fileName": "Sample File",
    "fileId": "-Lp9mZdjF-UcpahcqSax",
    "languages": {
      "english": true,
      "spanish": true
    }
}
401

Unauthorized


GET /api/getFolders

Grabs the folder structure for the user account.


Parameters


apiKey string (header)
operationType (optional) string (query)

transcript, caption, voiceover

Responses


200

Search results matching criteria.

Example Value
{
    "root": {
        "-MbinFf_K-vvwlHbWjN4": {
            "-MaGbXUW6BHambRKS3Na": {
                "created": 1621645731853,
                "folderName": "Sample Files"
            },
            "created": 1623209085719,
            "folderName": "2020"
        },
        "-MbixMpLJ05xgjvwNnPm": {
            "-McCIYUrFqeXQGrEqQpR": {
                "created": 1623720867882,
                "folderName": "The Matrix",
                "channelId": "-MGuz0F2CU6pzuHfP7Nn"
            },
            "created": 1623211736468,
            "folderName": "English Folder",
            "channelId": "-MGuz0F2CU6pzuHfP7Nn"
        },
        "-Mbj-WpbV0LFuPjbyyKl": {
            "created": 1623212563868,
            "folderName": "Spanish Folder",
            "channelId": "-MGuzXHOmXTdpcr6VtEg"
        },
        "folderName": "root"
    }
}
401

Unauthorized


GET /api/getChannels

Grabs the channel list with key id and fetches channel information.


Parameters


apiKey string (header)

Responses


200

Search results matching criteria.

Example Value
{
    "-MGtT13Qws8eFJjpct-S": {
      "channelName": "Marketing Team"
    },
    "-MI4baMqqZNlzJ1y38u3": {
      "channelName": "Collaboration Team"
    }
}
401

Unauthorized


POST /api/moveFile

Moves a file to a specific channel/folder.


Parameters


Content-Type application/json
apiKey string (header)
requestObject (body)
MoveRequest
Example Value
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
  "operationType": "voiceover", #transcription, caption, voiceover
  "folderPath": "root/-MdGjgD4xLtKRZHRQls_",
  "channelId": "-MGsa3fPlGmTUd52mH64"
}

Responses


200

Item moved.

Return Type
Example Value
{
  "message": "File moved successfully."
}
400

Invalid url, invalid body.

401

Unauthorized


POST /api/createFolder

Creates a new folder within file system.


Parameters


Content-Type application/json
apiKey string (header)
requestObject (body)
CreateFolderRequest
Example Value
{
  "folderName": "2021 collections folder",
  "folderPath": "root/-MdGjgD4xLtKRZHRQls_",
  "operationType": "voiceover", #transcription, caption, voiceover
  "channelId": "-MGsa3fPlGmTUd52mH64"
}

Responses


200

Item created.

Return Type
Example Value
{
  "message": "Folder created successfully.",
  "folderPath": "root/-MdGjgD4xLtKRZHRQls_/-MfIqYUk-D15SBEZL-9p"
}
400

Invalid url, invalid body.

401

Unauthorized


POST /api/createChannel

Creates a new channel inside the team associated with apiKey.


Parameters


Content-Type application/json
apiKey string (header)
requestObject (body)
CreateChannelRequest
Example Value
{
  "channelName": "German content channel",
}

Responses


200

Channel created.

Return Type
Example Value
{
  "message": "Channel created successfully.",
  "channelId": "-MSsS3fPlGmwZd52mHT1"
}
400

Invalid url, invalid body.

401

Unauthorized


Export

POST /api/exportFile

Initiates a new export job.


Parameters


Content-Type application/json
apiKey string (header)
requestObject (body)
ExportRequest
Example Value
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
 "operationType": "voiceover", caption, voiceover
  "targetLanguages": {
    "french": true,
    "spanish": true
  },
  "numberOfLines": 1,
  "charactersPerLine": 32,
  "showSpeakerNames": true,
  "subtitleFileType": "vtt",
  "shiftTime": 10000
}

Responses


201

Export job started.

Return Type
Example Value
{
  "fileUrl": "https://media-bucket.s3.amazonaws.com/Lx5wg13hNyNgaoyk616iztEZBy42/X0Si-yeYFkM5R9AKK_-Po.mp4"
}
400

Invalid input, object invalid.

401

Unauthorized


Dictionary

GET /api/dictionary

Grabs the dictionary list with key ID.


Parameters


searchString string (query)

pass dictionary key if left empty will grab a map of dictionary

Responses


200

Search results matching criteria.

Return Type
Example Value
{
  "id": "-MQMsO7Fc-5TkRMbiB6A",
  "dictionaryName": "Sample Dictionary",
  "dictionaryItem": {
    "phrase": "LLC",
    "boost": 20
  }
}
400

Bad input parameter.

401

Unauthorized


POST /api/dictionary

Adds a dictionary item.


Parameters


Content-Type application/json
requestObject (body)

Adds a phrase to the dictionary

dictionaryRequest
Example Value
{
  "phrase": "LLC",
  "dictionaryKey": "-MQMsk4sRXqrGH6DVgCG",
  "boost": 20
}

Responses


201

Item created.

Return Type
Example Value
{
  "id": "-MQMsO7Fc-5TkRMbiB6A",
  "dictionaryName": "Sample Dictionary",
  "dictionaryItem": {
    "phrase": "LLC",
    "boost": 20
  }
}
400

Invalid input, object invalid.

401

Unauthorized


Organizational

GET /api/getCredits

Returns the available credit allotment within the account.


Parameters


apiKey string (header)

Responses


200

Search results matching criteria.

Return Type
Example Value
{
    "nonExpiringCredits": 1234,
    "monthlyCredits": 567
}
401

Unauthorized


Models

CreditsMap
nonExpiringCredits
example: 1234
monthlyCredits
example: 567
DictionaryItem
phrase (required)
example: LLC
boost (optional)
Integer An importance value from 1 to 20 with 20 being the highest
example: 20
DictionaryMap
id
String format: id
example: -MQMsO7Fc-5TkRMbiB6A
dictionaryName
example: Sample Dictionary
dictionaryItem
DictionaryRequest
phrase (required)
example: LLC
dictionaryKey (required)
example: -MQMsk4sRXqrGH6DVgCG
boost (optional)
Integer An importance value from 1 to 20 with 20 being the highest
example: 20
ExportRequest
fileId (required)
example: -MQMsk4sRXqrGH6DVgCG
targetLanguages (required)
example: {"french":true,"spanish":true}
numberOfLines (optional)
Integer Accepts either 1 or 2.
example: 1
charactersPerLine (optional)
Integer Defaulted to 32. Accepts values between 10 and 70
example: 32
showSpeakerNames (optional)
Boolean Defaulted to false.
example: true
subtitleFileType (optional)
String Can be set as vtt or srt, defaulted to vtt
example: vtt
ExportResponse
fileUrl
example: https://media-bucket.s3.amazonaws.com/Lx5wg13hNyNgaoyk616iztEZBy42/X0Si-yeYFkM5R9AKK_-Po.mp4
FilesMap
edited (optional)
Integer format: id
example: 1569004761852
created (optional)
Integer format: id
example: 1569004761852
duration (optional)
example: 12.399438
fileName (optional)
example: Sample File
fileId (optional)
example: -Lp9mZdjF-UcpahcqSax
languages (optional)
LanguageItem
english
example: true
spanish
example: true
UploadRequest
fileUrl (required)
example: https://random.publicfilepath.mp4
fileName (required)
example: Sample file name
mediaType (required)
example: video/mp4
audioLanguage (required)
example: en-US
speakerCount (required)
Integer Speaker count value between 1-10
example: 2
dictionaryKey (optional)
example: default
channelId (optional)
example: -MGsa3fPlGmTUd52mH64
folderPath (optional)
example: root/-MbixMpLJ05xgjvwNnPm/-McCIYUrFqeXQGrEqQpR
targetLanguages (optional)
example: {"french":true,"spanish":true}
UploadResponse
fileId
example: -MQMsk4sRXqrGH6DVgCG
message
example: Import job has been started.
ImportSubtitleRequest
fileId (required)
example: -MGsa3fPlGmTUd52mH64
targetLanguage (required)
example: english
subtitleType (required)
example: vtt
subtitleUrl (required)
example: https://random.publicsubtitlefilepath.vtt
ImportSubtitleResponse
fileId
example: -MQMsk4sRXqrGH6DVgCG
message
example: Import Subtitle request has been sent.
TranslateRequest
fileId (required)
example: -MQMsk4sRXqrGH6DVgCG
targetLanguages (required)
example: {"french":true,"spanish":true}
TranslateResponse
message
example: Translation generated.
MoveRequest
fileId (required)
example: -MQMsk4sRXqrGH6DVgCG
folderPath (required)
example: root/-MdGjgD4xLtKRZHRQls_
channelId (optional) Maestra Teams only
example: -MGsa3fPlGmTUd52mH64
MoveResponse
message
example: File moved successfully.
CreateFolderRequest
folderName (required)
example: 2021 collections folder
folderPath (required)
Path that the folder will be created in.
example: root/-MdGjgD4xLtKRZHRQls_
channelId (optional) Maestra Teams only
example: -MGsa3fPlGmTUd52mH64
CreateFolderResponse
message
example: Folder created successfully.
folderPath
example: root/-MdGjgD4xLtKRZHRQls_/-MfIqYUk-D15SBEZL-9p
CreateChannelRequest
channelName (required)
example: German content channel
CreateChannelResponse
message
example: Channel created successfully.
channelId
example: -MSsS3fPlGmwZd52mHT1

Languages

Transcription Languages

Code Language English Name
"af-ZA" Afrikaans (Suid-Afrika) Afrikaans (South Africa)
"am-ET" አማርኛ (ኢትዮጵያ) Amharic (Ethiopia)
"hy-AM" Հայ (Հայաստան) Armenian (Armenia)
"az-AZ" Azərbaycan (Azərbaycan) Azerbaijani (Azerbaijan)
"id-ID" Bahasa Indonesia (Indonesia) Indonesian (Indonesia)
"ms-MY" Bahasa Melayu (Malaysia) Malay (Malaysia)
"bn-BD" বাংলা (বাংলাদেশ) Bengali (Bangladesh)
"bn-IN" বাংলা (ভারত) Bengali (India)
"ca-ES" Català (Espanya) Catalan (Spain)
"cs-CZ" Čeština (Česká republika) Czech (Czech Republic)
"da-DK" Dansk (Danmark) Danish (Denmark)
"de-DE" Deutsch (Deutschland) German (Germany)
"en-US" English English
"es-ES" Español (España) Spanish (Spain)
"es-US" Español (Estados Unidos) Spanish (United States)
"eu-ES" Euskara (Espainia) Basque (Spain)
"fil-PH" Filipino (Pilipinas) Filipino (Philippines)
"fr-CA" Français (Canada) French (Canada)
"fr-FR" Français (France) French (France)
"gl-ES" Galego (España) Galician (Spain)
"ka-GE" ქართული (საქართველო) Georgian (Georgia)
"gu-IN" ગુજરાતી (ભારત) Gujarati (India)
"hr-HR" Hrvatski (Hrvatska) Croatian (Croatia)
"zu-ZA" IsiZulu (Ningizimu Afrika) Zulu (South Africa)
"is-IS" Íslenska (Ísland) Icelandic (Iceland)
"it-IT" Italiano (Italia) Italian (Italy)
"jv-ID" Jawa (Indonesia) Javanese (Indonesia)
"kn-IN" ಕನ್ನಡ (ಭಾರತ) Kannada (India)
"km-KH" ភាសាខ្មែរ (កម្ពុជា) Khmer (Cambodia)
"lo-LA" ລາວ (ລາວ) Lao (Laos)
"lv-LV" Latviešu (latviešu) Latvian (Latvia)
"lt-LT" Lietuvių (Lietuva) Lithuanian (Lithuania)
"hu-HU" Magyar (Magyarország) Hungarian (Hungary)
"ml-IN" മലയാളം (ഇന്ത്യ) Malayalam (India)
"mr-IN" मराठी (भारत) Marathi (India)
"nl-NL" Nederlands (Nederland) Dutch (Netherlands)
"ne-NP" नेपाली (नेपाल) Nepali (Nepal)
"nb-NO" Norsk bokmål (Norge) Norwegian Bokmål (Norway)
"pl-PL" Polski (Polska) Polish (Poland)
"pt-BR" Português (Brasil) Portuguese (Brazil)
"pt-PT" Português (Portugal) Portuguese (Portugal)
"ro-RO" Română (România) Romanian (Romania)
"si-LK" සිංහල (ශ්රී ලංකාව) Sinhala (Sri Lanka)
"sk-SK" Slovenčina (Slovensko) Slovak (Slovakia)
"sl-SI" Slovenščina (Slovenija) Slovenian (Slovenia)
"su-ID" Urang (Indonesia) Sundanese (Indonesia)
"sw-TZ" Swahili (Tanzania) Swahili (Tanzania)
"sw-KE" Swahili (Kenya) Swahili (Kenya)
"fi-FI" Suomi (Suomi) Finnish (Finland)
"sv-SE" Svenska (Sverige) Swedish (Sweden)
"ta-IN" தமிழ் (இந்தியா) Tamil (India)
"ta-SG" தமிழ் (சிங்கப்பூர்) Tamil (Singapore)
"ta-LK" தமிழ் (இலங்கை) Tamil (Sri Lanka)
"ta-MY" தமிழ் (மலேசியா) Tamil (Malaysia)
"te-IN" తెలుగు (భారతదేశం) Telugu (India)
"vi-VN" Tiếng Việt (Việt Nam) Vietnamese (Vietnam)
"tr-TR" Türkçe (Türkiye) Turkish (Turkey)
"ur-PK" اردو (پاکستان) Urdu (Pakistan)
"ur-IN" اردو (بھارت) Urdu (India)
"el-GR" Ελληνικά (Ελλάδα) Greek (Greece)
"bg-BG" Български (България) Bulgarian (Bulgaria)
"ru-RU" Русский (Россия) Russian (Russia)
"sr-RS" Српски (Србија) Serbian (Serbia)
"uk-UA" Українська (Україна) Ukrainian (Ukraine)
"he-IL" עברית (ישראל) Hebrew (Israel)
"ar-IL" العربية (إسرائيل) Arabic (Israel)
"ar-JO" العربية (الأردن) Arabic (Jordan)
"ar-AE" العربية (الإمارات) Arabic (United Arab Emirates)
"ar-BH" العربية (البحرين) Arabic (Bahrain)
"ar-DZ" العربية (الجزائر) Arabic (Algeria)
"ar-SA" العربية (السعودية) Arabic (Saudi Arabia)
"ar-IQ" العربية (العراق) Arabic (Iraq)
"ar-KW" العربية (الكويت) Arabic (Kuwait)
"ar-MA" العربية (المغرب) Arabic (Morocco)
"ar-TN" العربية (تونس) Arabic (Tunisia)
"ar-OM" العربية (عُمان) Arabic (Oman)
"ar-PS" العربية (فلسطين) Arabic (State of Palestine)
"ar-QA" العربية (قطر) Arabic (Qatar)
"ar-LB" العربية (لبنان) Arabic (Lebanon)
"ar-EG" العربية (مصر) Arabic (Egypt)
"fa-IR" فارسی (ایران) Persian (Iran)
"hi-IN" हिन्दी (भारत) Hindi (India)
"th-TH" ไทย (ประเทศไทย) Thai (Thailand)
"ko-KR" 한국어 (대한민국) Korean (South Korea)
"cmn-Hant-TW" 國語 (台灣) Chinese, Mandarin (Traditional, Taiwan)
"yue-Hant-HK" 廣東話 (香港) Chinese, Cantonese (Traditional, Hong Kong)
"ja-JP" 日本語(日本) Japanese (Japan)
"cmn-Hans-HK" 普通話 (香港) Chinese, Mandarin (Simplified, Hong Kong)
"cmn-Hans-CN" 普通话 (中国大陆) Chinese, Mandarin (Simplified, China)

Translation Target Languages

  • "afrikaans"
  • "albanian"
  • "amharic"
  • "arabic"
  • "armenian"
  • "azerbaijani"
  • "basque"
  • "belarusian"
  • "bengali"
  • "bosnian"
  • "bulgarian"
  • "burmese"
  • "catalan"
  • "chinese"
  • "chineset"
  • "croatian"
  • "czech"
  • "danish"
  • "dutch"
  • "english"
  • "estonian"
  • "finnish"
  • "french"
  • "frenchc"
  • "burmese"
  • "georgian"
  • "german"
  • "greek"
  • "haitian creole"
  • "hebrew"
  • "hindi"
  • "hungarian"
  • "icelandic"
  • "indonesian"
  • "italian"
  • "japanese"
  • "kazakh"
  • "khmer"
  • "korean"
  • "kurdish"
  • "kyrgyz"
  • "latin"
  • "latvian"
  • "lithuanian"
  • "luxembourgish"
  • "macedonian"
  • "malay"
  • "maltese"
  • "nepali"
  • "norwegian"
  • "persian"
  • "polish"
  • "portuguese"
  • "punjabi"
  • "romanian"
  • "russian"
  • "samoan"
  • "serbian"
  • "slovak"
  • "slovenian"
  • "somali"
  • "spanish"
  • "swedish"
  • "thai"
  • "turkish"
  • "ukrainian"
  • "urdu"
  • "uzbek"
  • "vietnamese"
  • "welsh"