API Documentation
General
Base Url: https://54i2k0z0vf.execute-api.cn-north-1.amazonaws.com.cn/prod/
Header | Required | Description |
---|---|---|
x-sdk-key1 | YES | Your SDK Key |
origin | YES | The origin 2 |
Content-Type | YES | application/json |
1. Your SDK Key.
2. The domain name you associated to that specific SDK key. In localhost, you don't need to specify that origin.
- The request for
GET
andDELETE
endpoints arequery-parameter
. - The request for
POST
andPUT
arejson
.
The response will always follow this format:
In case of success
{
data: DATA OBJECT
}
In case of error
{
error: 'ERROR MESSAGE'
}
Create an Event
- Create an event associated to your
SDK Key
. - You can see all your events from your dashboard
Request Parameters
- End Point
/events
- Method
POST
Body Parameter:
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
name | String | YES | Event Name | My SDK Event |
startDate | Integer | YES | Starting date/time of your event. Time Stamp (ms) | 1630496799164 |
endDate | Integer | YES | Ending date/time of your event. Time Stamp (ms) 1 | 1630501799164 |
streamType | Enum | YES | See the Original Stream section | vimeo |
streamUrl | String | YES | See the Original Stream section | |
hasRelay | Boolean | NO | true value will show the relay language button to the interpreters and let them act as relay. By default is false | true |
floorLanguage | String | YES | The main language of your event.2 | en-US |
subtitles | Enum | NO | Supported Values: '' , AISubtitles , AISubtitlesTranslation . '' empty string means you want to receive simultaneous interpretation only, AISubtitles means you want to receive AI recognized subtitles, AISubtitlesTranslation means you want to receive AI Translated subtitles. | '' |
1. The ending date must always be after the starting date.
2. See Akkadu's supported languages.
Original Stream
The interpreter requires to see the original audio/video that he has to translate. When creating/editing an event we have several attributes which allow you to config the event for different types of sources.
streamType | streamUrl | format | comments |
---|---|---|---|
none | empty | ||
youtube | required | Valid youtube URL | |
vimeo | required | Valid vimeo URL | |
m3u8 | required | https URL that ends with .m3u8 | |
iframe | required | https URL. | Your iframe will require import our iframe script in order to make the interpreter volume controls work properly |
flv | required | https URL that ends with .flv | |
akkaduPushRtmp | empty | akkaduPushRtmp is a push RTMP URL provided by Akkadu where you will push your original stream. The push RTMP url has this format: rtmp://live.akkadu.com:1935/{Your Room Name}/{Your API key} . If you select akkaduPushRtmp leave the parameter streamUrl empty. |
HTTP Request example
POST /events
Accept: application/json
x-sdk-key: {YOUR-KEY}
{
"name": "My SDK Event",
"startDate": 1630496799164,
"endDate": 1630501799164,
"streamUrl": "https://akkadu.com",
"streamType": "other",
"floorLanguage": "en-US",
"hasRelay": true,
"subtitles": ""
}
HTTP Response Example
{
{
"data": {
"event": {
"roomName": "zved", // Unique room name of your event
"name": "My SDK Event", //Event readable name
"streamType": "iframe", // Type of stream
"streamUrl": "https://my-domain.com",
"floorLanguage": "en-US", // The main language of your event
"startDate": 1630496799164, // Starting date/time of your event
"endDate": 1630501799164 // Ending date/time of your event
"hasRelay": true, // Whether act as relay language is enabled or not
"subtitles": "" // Type of subtitles or blank
}
},
}
Update an Event
Update an existing event using the roomName
of the event.
Request Parameters
End Point
/events
Method
PUT
Query parameters:
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
roomName | String | YES | The event you want to edit | zved |
Body parameters:
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
name | String | NO | Event name | My SDK Event |
startDate | Integer | NO | Starting date/time of your event. Time Stamp (ms) | 1630496799164 |
endDate | Integer | NO | Ending date/time of your event. Time Stamp (ms) 1 | 1630501799164 |
streamUrl | String | NO | See the Original Stream section | |
streamType | Enum | NO | See the Original Stream section | vimeo |
hasRelay | Boolean | NO | true value will show the relay language button to the interpreters and let them act as relay. By default is false | true |
floorLanguage | String | NO | The main language of your event.2. You can not update this value to a language used as interpreted language | en-US |
subtitles | Enum | NO | Supported Values: '' , AISubtitles , AISubtitlesTranslation . '' empty string means you want to receive simultaneous interpretation only, AISubtitles means you want to receive AI recognized subtitles, AISubtitlesTranslation means you want to receive AI Translated subtitles. | '' |
1. The ending date must always be after the starting date.
2. See Akkadu's supported languages.
We have extra parameters to config the floor language when we stream the output of it together the interpreted streams. You can read more in Interpreter Stream Types section.
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
floorPushUrlType | Enum | NO | Empty string or rtmp . Setting it to rtmp also requires to provide a valid floorRtmpKey and a key as floorPushUrl in the request body | rtmp |
floorPushUrl | String | NO | Must be a valid url according to the selected type. | en-US |
floorRtmpKey | String | NO | Floor RTMP Url key, when the type rtmp is selected. | my-key |
floorPushVideo | Boolean | NO | false means you only want to receive the interpreted audio, true means you want to receive video + interpreted audio. | false |
HTTP Request example
PUT /events?roomName={ROOM_NAME}
Accept: application/json
x-sdk-key: {YOUR-KEY}
{
"name": "My SDK Event",
"startDate": 1630496799164,
"endDate": 1630501799164,
"streamUrl": "https://akkadu.com",
"streamType": "other",
"floorLanguage": "en-US",
"hasRelay": false,
"subtitles": "" // Type of subtitles or blank
"floorPushUrlType": "",
"floorPushUrl": "",
"floorRtmpKey": "",
"floorPushVideo": false
}
HTTP Response Example
{
{
"data": {
"event": {
"roomName": "zved", // Unique room name of your event
"name": "My SDK Event", //Event readable name
"streamType": "iframe", // Type of stream
"streamUrl": "https://my-domain.com",
"floorLanguage": "en-US",
"startDate": 1630496799164, // Starting date/time of your event
"endDate": 1630501799164 // Ending date/time of your event
"hasRelay": false // Whether act as relay language is enabled or not
"subtitles": "", // Type of subtitles or blank
"floorPushUrlType": "", // 'rtmp' or ''
"floorPushUrl": "", // A valid RTMP URL if the floorPushUrlType is rtmp.
"floorRtmpKey": "", // A string RTMP key if the floorPushUrlType is rtmp.
"floorPushVideo": false // Weather you want to receive only audio or audio + video.
}
},
}
HTTP Example of Floor with RTMP Options
Only in the case of AISubtitlesTranslation AISubtitlesTranslation
subtitles otpion you can config RTMP parameters in this end point.
PUT /events?roomName={ROOM_NAME}
Accept: application/json
x-sdk-key: {YOUR-KEY}
{
"floorPushUrlType": "rtmp",
"floorPushUrl": "rtmp://myweb.com/application/path",
"floorRtmpKey": "my-rtmp-key",
"floorPushVideo": true
}
Delete an Event
Delete an event by roomName
.
Request Parameters
End Point
/events
Method
DELETE
Query parameters:
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
roomName | String | YES | Delete by roomName | zved |
HTTP Request example
DELETE /events?roomName={ROOM_NAME}
Accept: application/json
x-sdk-key: {YOUR-KEY}
HTTP Response Example
We return the deleted event:
{
{
"data": {
"event": {
"roomName": "zved", // Unique room name of your event
"name": "My SDK Event", //Event readable name
"streamType": "iframe", // Type of stream
"streamUrl": "https://my-domain.com",
"floorLanguage": "en-US",
"startDate": 1630496799164, // Starting date/time of your event
"endDate": 1630501799164, // Ending date/time of your event
"hasRelay": false // Whether act as relay language is enabled or not
}
},
}
Get Languages
Get all the languages supported by Akkadu for translation.
Request Parameters
End Point /events/languages
Method: GET
- No parameters are required.
HTTP Request example
GET /events/languages
Accept: application/json
HTTP Response Example
{
"data": {
"languages": [
{
"name": "English", //Language Label
"code": "en-US" // Language Code
},
{
"name": "Chinese",
"code": "zh-CN"
},
{
"name": "Spanish",
"code": "es-ES"
}
}
}
Get Event List
- Get the list of all the events associated to a specific
SDK KEY
.['abcd','gfht']
- You can also query by
roomName
.
Request Parameters
End Point
/events
Method
GET
Query parameters:
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
roomName | String | NO | Filter by room name1 | zved |
- If the room name doesn`t exist, it will throw
404 Not found error
. Otherwise you will get an array with one item only.
HTTP Request example
GET /events HTTP/1.1
Accept: application/json
x-sdk-key: {YOUR-KEY}
HTTP Response Example
We return the deleted event
{
"data": {
"events": [
{
"roomName": "zved", // Unique room name of your event
"name": "My SDK Event", //Event readable name
"streamType": "iframe", // Type of stream
"streamUrl": "https://my-domain.com",
"floorLanguage": "en-US",
"startDate": 1630496799164, // Starting date/time of your event
"endDate": 1630501799164 // Ending date/time of your event
"hasRelay": true, // Whether act as relay language is enabled or not
"subtitles": "", // Type of subtitles or blank
"floorPushUrlType": "", // 'rtmp' or ''
"floorPushUrl": "", // A valid RTMP URL if the floorPushUrlType is rtmp.
"floorRtmpKey": "", // A string RTMP key if the floorPushUrlType is rtmp.
"floorPushVideo": false, // Weather you want to receive only audio or audio + video
"languages": [
{
"languages": "es-ES", // Language Code
"pushUrl": "rtmps://media-service-url/path/key", // RTMP push URL
"interpreters": ["interpreter1@akkadu.com", "interpreter2@akkadu.com"] // List of intepreters's emails
},
{
"languages": "fr-FR",
"pushUrl": "rtmps://media-service-url/path/key", // RTMP push URL
"interpreters": ["interpreter3@akkadu.com", "interpreter4@akkadu.com"]
}
]
}
]
},
}
Update the interpreters of an event
- Each language of your event must have at least one interpreter.
- Usually, the interpretation is performed by a pair of interpreters.
- The interpreter must have previously registered in Akkadu dashboard
- The chosen language code cannot be the same as the floor's language code. (The original language of your event)
Request Parameters
End Point
/events/interpreters
Method
PUT
Query parameters:
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
roomName | String | YES | The event you want to edit | zved |
Body parameters:
Parameter | Type | Required | Description | Example |
---|---|---|---|---|
languageCode | String | YES | Supported Language Code 1 | es-ES |
pair1 | String | NO | Interpreter's email2 3 or empty string '' | interpreter1@akkadu.com |
pair2 | String | NO | Interpreter's email2 3 or empty string '' | interpreter2@akkadu.com |
pushUrlType | String | NO | Check Interpreter Stream Types | rtmp or '' |
pushUrl | String | NO | Check Interpreter Stream Types | rtmps://my-media-server/path/key or '' |
pushVideo | Boolean | NO | Specific pushUrlTypes allow to push also the video. Check Interpreter Stream Types | false |
rtmpKey | String | NO | Specific RTMP pushUrlTypes require to include the rtmpKey | 123123 |
1. See Akkadu's supported languages.
2. The interpreter's email has to be registered in Akkadu
3. The error instance failed to match exactly one schema (matched 0 out of 2)]
means that the value shall be empty string or a valid email/url according to the parameter requirement.
Interpreter Stream
The interpreters translation (synced with the source video if set) can be pushed to a URL which you can display to your audience.
pushUrlType | pushUrl | pushVideo | comments |
---|---|---|---|
none | empty | - | |
rtmp | required | true or false | Requires to be a valid url with rtmp , rtmps protocol or empty string '' . When pushUrl is set we will live stream the interpreted audio to this push RTMP url for this language. pushUrl key must be different for each language code |
Error Codes
Code | Description |
---|---|
400 | The parameters are wrong, or the required parameters are missing |
401 | Not authorized. Your SDK Key is wrong or missing, or the origin is not matching the SDK key |
403 | Forbidden. The operation is valid but not with the current values |
404 | Not found (Check the message to know what wasn`t found) |
409 | Conflict, some data is duplicated or not allowed. |
412 | Internal Call Error |
500 | Internal Server Error |
HTTP Request example
PUT /events/interpreters?roomName={}
Accept: application/json
x-sdk-key: {YOUR-KEY}
{
"languageCode": "es-ES", # Language code
"pair1": "interpreter1@akkadu.com", # Interpreter's email *
"pair2": "interpreter2@akkadu.com", # Interpreter's email
"pushUrl": "rtmps://my-media-server/path/key" # RTMP Push URL
}
HTTP Response Example
We return the updated language
{
"data": {
{
"languageCode": "es-ES",
"pair1": "interpreter1@akkadu.com",
"pair2": "interpreter2@akkadu.com",
"pushUrl": "rtmps://my-media-server/path/key"
},
},
}