API Documentation

General

Base Url: https://54i2k0z0vf.execute-api.cn-north-1.amazonaws.com.cn/prod/

Header	Required	Description
x-sdk-key₁	YES	Your SDK Key
origin	YES	The origin ₂
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 and DELETE endpoints are query-parameter.
The request for POST and PUT are json.

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) ₁	`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.₂	`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) ₁	`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.₂. 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 name₁	`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 ₁	`es-ES`
pair1	String	NO	Interpreter's email₂ ₃ or empty string `''`	`interpreter1@akkadu.com`
pair2	String	NO	Interpreter's email₂ ₃ 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"
    },
  },
}

Step by Step Tutorial

Translation Agencies

# API Documentation

# General

# Create an Event

# Request Parameters

# Original Stream

# HTTP Request example

# HTTP Response Example

# Update an Event

# Request Parameters

# HTTP Request example

# HTTP Response Example

# HTTP Example of Floor with RTMP Options

# Delete an Event

# Request Parameters

# HTTP Request example

# HTTP Response Example

# Get Languages

# Request Parameters

# HTTP Request example

# HTTP Response Example

# Get Event List

# Request Parameters

# HTTP Request example

# HTTP Response Example

# Update the interpreters of an event

# Request Parameters

# Interpreter Stream

# Error Codes

# HTTP Request example

# HTTP Response Example

API Documentation

General

Create an Event

Request Parameters

Original Stream

HTTP Request example

HTTP Response Example

Update an Event

Request Parameters

HTTP Request example

HTTP Response Example

HTTP Example of Floor with RTMP Options

Delete an Event

Request Parameters

HTTP Request example

HTTP Response Example

Get Languages

Request Parameters

HTTP Request example

HTTP Response Example

Get Event List

Request Parameters

HTTP Request example

HTTP Response Example

Update the interpreters of an event

Request Parameters

Interpreter Stream

Error Codes

HTTP Request example

HTTP Response Example