• Account
    • Get Credits
  • Channels
    • Get Channels
    • Create Channel
  • Dictionaries
    • Get Dictionary
  • Files
    • Get Files
    • Export File
    • Move File
  • Folders
    • Get Folders
    • Create Folder
  • Import
    • Upload File
  • Subtitles
    • Import Subtitle
  • Translation
    • Translate
  • Voice-cloning
    • Clone Voice from User Audio
    • Remove Cloned Voice
    • Get Cloned Voice Names and IDs
  • Voiceover
    • Generate Voiceover
    • Set Default Speakers
    • Export Voiceover
    • Get Voice Sample
    • List Voices

Files

Get Files

GET/api/getFiles

Grabs the file list with key id and basic information

Parameters

apiKeyRequiredheaderstring

API key for authentication

fileIdOptionalbodystring

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

operationTypeOptionalbodystring

e.g., transcript, caption, voiceover

Example request
1234567891011
fetch('https://companion.maestrasuite.com/api/getFiles', {
  method: 'GET',
  headers: {
	"apiKey": "<YOUR_API_KEY>"
  },
  body: JSON.stringify({
	"fileId": "-Lp9mZdjF-UcpahcqSadsa",
	"operationType": "transcript" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
1234567891011121314
{
  "-OGZNECLNRdQKpooDh0Y": {
    "duration": 58.147007,
    "edited": 1737354728550,
    "created": 1736850866422,
    "fileName": "test2",
    "folderPath": "root",
    "languages": {
      "english": true
    },
    "status": "done",
    "fileId": "-OGZNECLNRdQKpooDh0Y"
  }
}

Export File

POST/api/exportFile

Generate an export link for the requested transcript or subtitle file

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

Must be application/json

fileIdRequiredbodystring

ID of the file to export

operationTypeRequiredbodystring

Type of the operation

targetLanguagesOptionalbodyobject

*Required if vtt or srt export not if json export

numberOfLinesOptionalbodyinteger

Number of lines to include in the export, accepts either 1 or 2

charactersPerLineOptionalbodyinteger

Defaulted to 32. Accepts values between 10 and 70

showSpeakerNamesOptionalbodyboolean

Whether to show speaker names in the export

fileTypeOptionalbodystring

Can be set as vtt, srt or json, defaulted to vtt. targetLanguages parameter is invalid if set as json

Example request
1234567891011121314151617
fetch('https://companion.maestrasuite.com/api/exportFile', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"fileId": "-MQMsk4sRXqrGH6DVgCG",
	"operationType": "transcript",
	"targetLanguages": {"french":true,"spanish":true},
	"numberOfLines": 2,
	"charactersPerLine": 32,
	"showSpeakerNames": false,
	"fileType": "vtt" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
12345
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
  "exportUrl": "https://maestra-exports/exports/abc123.srt",
  "message": "Export link successfully generated."
}

Move File

POST/api/moveFile

Moves a file to a specific channel/folder

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

Must be application/json

fileIdRequiredbodystring

The ID of the file to move

operationTypeRequiredbodystring

Type of the operation

folderPathRequiredbodystring

Path of the folder

channelIdOptionalbodystring

ID of the channel (Maestra Teams only)

Example request
1234567891011121314
fetch('https://companion.maestrasuite.com/api/moveFile', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"fileId": "-MQMsk4sRXqrGH6DVgCG",
	"operationType": "voiceover",
	"folderPath": "root",
	"channelId": "-MGsa3fPlGmTUd52mH64" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
123
{
  "message": "File moved successfully."
}

Channels

Get Channels

GET/api/getChannels

Retrieve a list of channels for a particular workspace

Parameters

apiKeyRequiredheaderstring

API key for authentication

Example request
12345678
fetch('https://companion.maestrasuite.com/api/getChannels', {
  method: 'GET',
  headers: {
	"apiKey": "<YOUR_API_KEY>"
  },
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
123456789101112
[
  {
    "channelId": "-MGsa3fPlGmTUd52mH64",
    "channelName": "Channel A",
    "workspaceId": "workspace_12345"
  },
  {
    "channelId": "-MGsa3fPlGmTUd52mABC",
    "channelName": "Channel B",
    "workspaceId": "workspace_12345"
  }
]

Create Channel

POST/api/createChannel

Create a new channel within a workspace

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

application/json

channelNameRequiredbodystring

Name of the channel

Example request
1234567891011
fetch('https://companion.maestrasuite.com/api/createChannel', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"channelName": "My New Channel" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
1234
{
  "channelId": "-MQMsk4sRXqrGH6DVgCG",
  "message": "Channel has been created."
}

Dictionaries

Get Dictionary

GET/api/dictionary

Grabs the dictionary list with key ID.

Parameters

apiKeyRequiredheaderstring

API key for authentication

dictionaryIdOptionalbodystring

The ID of the dictionary to retrieve, if not provided, returns all dictionaries

Example request
12345678910
fetch('https://companion.maestrasuite.com/api/dictionary', {
  method: 'GET',
  headers: {
	"apiKey": "<YOUR_API_KEY>"
  },
  body: JSON.stringify({
	"dictionaryId": "-MGsa3fPlGmTUd52mH64" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
1234567891011121314
{
  "dictionaryId": "-MGsa3fPlGmTUd52mH64",
  "title": "Technical Terms",
  "entries": [
    {
      "word": "cardiomyopathy",
      "replacement": "cardiomyopathy"
    },
    {
      "word": "hypertension",
      "replacement": "hypertension"
    }
  ]
}

Folders

Get Folders

GET/api/getFolders

Grabs the folder structure for the user account

Parameters

apiKeyRequiredheaderstring

API key for authentication

operationTypeOptionalbodystring

e.g., transcript, caption, voiceover

Example request
12345678910
fetch('https://companion.maestrasuite.com/api/getFolders', {
  method: 'GET',
  headers: {
	"apiKey": "<YOUR_API_KEY>"
  },
  body: JSON.stringify({
	"operationType": "transcript" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
12345678910111213141516171819202122232425262728
{
  "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"
  }
}

Create Folder

POST/api/createFolder

Creates a new folder within file system

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

Must be application/json

folderNameRequiredbodystring

Name of the folder

folderPathRequiredbodystring

Path of the folder

operationTypeRequiredbodystring

Type of the operation

channelIdOptionalbodystring

ID of the channel (Maestra Teams only)

Example request
1234567891011121314
fetch('https://companion.maestrasuite.com/api/createFolder', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"folderName": "2021 collections folder",
	"folderPath": "root/-MdGjgD4xLtKRZHRQls_",
	"operationType": "voiceover",
	"channelId": "-MGsa3fPlGmTUd52mH64" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
1234
{
  "message": "Folder created successfully.",
  "folderPath": "root/-MdGjgD4xLtKRZHRQls_/-MfIqYUk-D15SBEZL-9p"
}

Import

Upload File

POST/api/uploadFile

Initiates a new file upload to Maestra

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

Must be application/json

fileUrlRequiredbodystring

URL of the file to upload

fileNameRequiredbodystring

Name of the file

mediaTypeRequiredbodystring

Type of the media

audioLanguageRequiredbodystring

Language of the audio

speakerCountRequiredbodyinteger

Number of speakers

dictionaryKeyOptionalbodystring

Key of the dictionary

channelIdOptionalbodystring

ID of the channel

folderPathOptionalbodystring

Path of the folder

operationTypeRequiredbodystring

Type of the operation

skipTranscriptionRequiredbodyboolean

Whether to skip transcription

targetLanguagesOptionalbodyobject

Target languages for the operation

Example request
123456789101112131415161718192021
fetch('https://companion.maestrasuite.com/api/uploadFile', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"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",
	"skipTranscription": false,
	"targetLanguages": {"french":true,"spanish":true} })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
1234
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
  "message": "Import job has been started."
}

Subtitles

Import Subtitle

POST/api/importSubtitle

Initiates a new subtitle file upload

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

Must be application/json

fileIdRequiredbodystring

The ID of the file to import subtitles for

operationTypeRequiredbodystring

Type of the operation

targetLanguageRequiredbodystring

Target language for the subtitles

subtitleTypeRequiredbodystring

Type of the subtitle file

subtitleUrlRequiredbodystring

URL of the subtitle file

Example request
123456789101112131415
fetch('https://companion.maestrasuite.com/api/importSubtitle', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"fileId": "-MGsa3fPlGmTUd52mH64",
	"operationType": "voiceover",
	"targetLanguage": "english",
	"subtitleType": "srt",
	"subtitleUrl": "https://random.publicsubtitlefilepath.srt" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
1234
{
  "fileId": "-MQMsk4sRXqrGH6DVgCG",
  "message": "Import Subtitle request has been sent."
}

Voiceover

Generate Voiceover

POST/api/generateVoiceover

Generates voiceover for a specific language

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

Must be application/json

fileIdRequiredbodystring

The ID of the file for which to generate voiceover

targetLanguagesRequiredbodyobject

Languages for which to generate voiceover

Example request
123456789101112
fetch('https://companion.maestrasuite.com/api/generateVoiceover', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"fileId": "-MQMsk4sRXqrGH6DVgCG",
	"targetLanguages": {"french":true,"spanish":true} })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
123
{
  "message": "Voiceover synthesis started."
}

Set Default Speakers

POST/api/setDefaultSpeakers

Sets the default speakers for various languages

Parameters

Content-TypeRequiredheaderstring

Must be application/json

apiKeyRequiredheaderstring

API key for authentication

requestArrayRequiredbodyarray

Array of speaker configurations. Index 0 sets default configuration for unspecified speakers, subsequent indices match speakers in audio files

Example request
12345678910
fetch('https://companion.maestrasuite.com/api/setDefaultSpeakers', {
  method: 'POST',
  headers: {
	"Content-Type": "application/json",
	"apiKey": "<YOUR_API_KEY>"
  },
  body: [{"arabic":"Salma","bengali":"Tanishaa","chinese":"Xiaoxiao"},{"danish":"Christel","dutch":"Colette","english":"Joanna"}]
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
123
{
  "message": "Default speakers are set."
}

Export Voiceover

POST/api/exportVoiceover

Exports voiceover for a specific file ID and language

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

Must be application/json

fileIdRequiredbodystring

The ID of the file for which to export voiceover

targetLanguagesRequiredbodyobject

Languages for which to export voiceover

Example request
123456789101112
fetch('https://companion.maestrasuite.com/api/exportVoiceover', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"fileId": "-MQMsk4sRXqrGH6DVgCG",
	"targetLanguages": {"german":true,"english":true} })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
123456
{
  "exportLinks": {
    "german": "https://storage.googleapis.com/maestro-218920.appspot.com/...",
    "english": "https://storage.googleapis.com/maestro-218920.appspot.com/..."
  }
}

Get Voice Sample

GET/api/getVoiceSample

Retrieves a voice sample for a given voice ID and language

Parameters

apiKeyRequiredheaderstring

API key for authentication

voiceIdRequiredbodystring

The ID of the voice sample to retrieve

languageRequiredbodystring

The language of the voice sample to retrieve

Example request
1234567891011
fetch('https://companion.maestrasuite.com/api/getVoiceSample', {
  method: 'GET',
  headers: {
	"apiKey": "<YOUR_API_KEY>"
  },
  body: JSON.stringify({
	"voiceId": "voice_123",
	"language": "en-US" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
123
{
  "voiceSampleURL": "https://example.com/voice_samples/sample.mp3"
}

List Voices

GET/api/listVoices

Lists all available voices, optionally grouped by language

Parameters

apiKeyRequiredheaderstring

API key for authentication

groupByLanguageOptionalbodyboolean

When set to true, groups the voices by their respective languages

Example request
12345678910
fetch('https://companion.maestrasuite.com/api/listVoices', {
  method: 'GET',
  headers: {
	"apiKey": "<YOUR_API_KEY>"
  },
  body: JSON.stringify({
	"groupByLanguage": "true" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
123456789101112
{
  "Adri": {
    "languages": {
      "afrikaans": {
        "South Africa": true
      }
    },
    "name": "Adri",
    "voiceId": "Adri",
    "pro": false
  }
}

Translation

Translate

POST/api/translate

Translates an existing file in the system

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

Must be application/json

fileIdRequiredbodystring

The ID of the file to translate

operationTypeRequiredbodystring

Type of the operation

targetLanguagesRequiredbodyobject

Languages for which to generate translation

Example request
12345678910111213
fetch('https://companion.maestrasuite.com/api/translate', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"fileId": "-MQMsk4sRXqrGH6DVgCG",
	"operationType": "voiceover",
	"targetLanguages": {"french":true,"spanish":true} })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
123
{
  "message": "Translation generated."
}

Account

Get Credits

GET/api/getCredits

Returns the available credit allotment within the account

Parameters

apiKeyRequiredheaderstring

API key for authentication

Example request
12345678
fetch('https://companion.maestrasuite.com/api/getCredits', {
  method: 'GET',
  headers: {
	"apiKey": "<YOUR_API_KEY>"
  },
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
1234
{
  "nonExpiringCredits": 1234,
  "monthlyCredits": 567
}

Voice-cloning

Clone Voice from User Audio

POST/api/cloneVoice/userAudio

Clones a user's voice using an audio file and stores it in the system.

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

application/json

fileUrlRequiredbodystring

URL of the user's audio file to be cloned

elevenLabsVoiceNameRequiredbodystring

Name for the cloned voice in Eleven Labs

Example request
123456789101112
fetch('https://companion.maestrasuite.com/api/cloneVoice/userAudio', {
  method: 'POST',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"fileUrl": "https://example.com/audio.mp3",
	"elevenLabsVoiceName": "My Cloned Voice" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
1234
{
  "voiceId": "abc123xyz",
  "message": "Voice cloned."
}

Remove Cloned Voice

DELETE/api/cloneVoice/remove

Removes a cloned voice associated with the user.

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

application/json

voiceIdRequiredbodystring

ID of the cloned voice to be removed

Example request
1234567891011
fetch('https://companion.maestrasuite.com/api/cloneVoice/remove', {
  method: 'DELETE',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
  body: JSON.stringify({
	"voiceId": "abc123xyz" })
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
123
{
  "message": "Clone voice removed."
}

Get Cloned Voice Names and IDs

GET/api/cloneVoice/namesIds

Retrieves a list of cloned voices for the authenticated user, including their names and IDs.

Parameters

apiKeyRequiredheaderstring

API key for authentication

Content-TypeRequiredheaderstring

application/json

Example request
123456789
fetch('https://companion.maestrasuite.com/api/cloneVoice/namesIds', {
  method: 'GET',
  headers: {
	"apiKey": "<YOUR_API_KEY>",
	"Content-Type": "application/json"
  },
}).then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));
Response
12345678910
[
  {
    "id": "abc123xyz",
    "name": "My Cloned Voice"
  },
  {
    "id": "def456uvw",
    "name": "Second Cloned Voice"
  }
]

Supported Languages

TranscriptionTranslationVoiceover
afrikaans
albanian
amharic
arabic(DeepL)(Clone/Pro)
armenian
assamese
azerbaijani
basque
belarusian
bengali
bosnian
bulgarian(DeepL)(Clone/Pro)
burmese
cantonese
catalan
chinese(Clone/Pro)
chineset(Clone/Pro)
croatian(Clone/Pro)
czech(DeepL)(Clone/Pro)
danish(DeepL, Glossary)(Clone/Pro)
dari
divehi
dutch(DeepL, Glossary)(Clone/Pro)
english(DeepL, Glossary)(Clone/Pro)
estonian
faroese
fijan
filipino(Clone/Pro)
finnish(DeepL)(Clone/Pro)
french(DeepL, Glossary)(Clone/Pro)
frenchc(Clone/Pro)
galician
georgian
german(DeepL, Glossary)(Clone/Pro)
greek(DeepL)(Clone/Pro)
gujarati
haitian creole
hausa
hebrew
hindi(Clone/Pro)
hmong daw
hungarian(DeepL)(Clone/Pro)
icelandic
igbo
indonesian(DeepL)(Clone/Pro)
inuinnaqtun
inuktitut
irish
italian(DeepL, Glossary)(Clone/Pro)
japanese(DeepL, Glossary)(Clone/Pro)
javanese
kannada
kazakh
khmer
kinyarwanda
klingon
korean(DeepL, Glossary)(Clone/Pro)
kurdish
kyrgyz
lao
latin
latvian(DeepL)
lithuanian(DeepL)
luxembourgish
macedonian
malagasy
malay(Clone/Pro)
malayalam
maltese
maori
marathi
mongolian
nepali
norwegian(DeepL, Glossary)(Clone/Pro)
odia
pashto
persian
polish(DeepL, Glossary)(Clone/Pro)
portuguese(DeepL, Glossary)(Clone/Pro)
portugueseb(Clone/Pro)
punjabi
romanian(DeepL, Glossary)(Clone/Pro)
russian(DeepL, Glossary)(Clone/Pro)
samoan
serbian
serbianl
shona
sinhala
slovak(DeepL)(Clone/Pro)
slovenian(DeepL)
somali
spanish(DeepL, Glossary)(Clone/Pro)
sundanese
swahili
swedish(DeepL, Glossary)(Clone/Pro)
tahitian
tamil(Clone/Pro)
tatar
telugu
thai
tibetan
tigrinya
tongan
turkish(DeepL)(Clone/Pro)
turkmen
ukrainian(Clone/Pro)
ukranian
urdu
uyghur
uzbek
vietnamese(Clone/Pro)
welsh
yoruba
zulu