NAV Navbar
python shell

Introduction

Welcome to the Cadence API! You can use our API to create new interpretation and translation jobs on Cadence’s platform.

Call Booking API

All methods must be called using HTTPS. Arguments can be passed as POST, with query params placed in the body of the JSON payload. The response contains a JSON object, which contains a top-level property status, indicating success or failure.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Bearer meowmeowmeow"

Make sure to replace meowmeowmeow with your API key.

API keys are used to authenticate users of our API. You can contact us to request a new API key.

The API key is expected to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer meowmeowmeow

Book a new call

curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer meowmeowmeow" '{"api_token": "meowmeowmeow"
, "start_time": "2017-02-14T13:15:03Z"
, "timezone": "Asia/Bangkok"
, "languages" : [1,20]
, "notes" : "This is a great job"}' "https://cadence2.bubbleapps.io/version-test/api/1.1/wf/create_job"

The above command returns JSON structured like this:

{
    "status": "success",
    "response": {
        "job_id": "1486939273049x736883949009633300",
        "job_start_time": "Friday, February 17, 2017 11:15 am",
        "job_timezone": "Europe/Lisbon",
        "job_duration": "10 to 60 minutes",
        "job_languages": "English, Malaysian",
        "job_active": true,
        "user_id": "1487026541060x869803193258121600"
    }
}

This endpoint creates a new call with given start time, timezone and languages on Cadence’s platform.

HTTP Request

POST https://cadence2.bubbleapps.io/version-test/api/1.1/wf/create_job

URL Parameters

Parameter Description
api_token Pre-assigned API token for authentication.
start_time The date and time at which the call will happen, expected in format YYYY-MM-DDTHH:mm:ssZ. Note the Z value does not have to be the timezone in which the local time is as long as the timezone field is specified.
timezone A string containing the “tz” ID of the local timezone in which the call will happen, such as “America/Los_Angeles” or “Asia/Shanghai”, as defined in IANA Time Zone Database and a list of available values can be found on Wikipedia.
languages A list of language IDs will be used in the call, e.g. [1,2,6] stands for English, Mandarin and French. Accepted languages and their ids can be found here (JSON)
notes Any additional information we need to know in order to serve you better.

Response

Property Description
response JSON object of the response, with fields listed below.
status Indicating request success or failure.

Fields of response object

Property Description
job_id The unique id of the created job.
job_start_time The date and time at which the call will happen.
job_timezone The local timezone in which the call will happen.
job_duration How long would the call take.
job_languages Languages will be used in the call.

Errors

The Smart-match API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The requested resouce is hidden for administrators only
404 Not Found – The specified resouce could not be found
405 Method Not Allowed – You tried to access an endpoint with an invalid method
406 Not Acceptable – You requested a format that isn’t json
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Twilio API

Cadence Translate provides high-accuracy transcription and voice-over translation services for Twilio, and its partners.

Installation and Configuration

There is no installation needed. The API accepts requests via HTTP POST to the URL

https://cadencetranscription.herokuapp.com/api

Runtime Request Parameters

The API requires the following parameters on any request:

Parameter Description
request_sid Unique identifier for this request (as in Twilio’s documentation )
callback_url Callback URL for the asynchronous response (as in Twilio’s documentation )
audio_data Audio file binary bytestream (as in Twilio’s documentation )
requested_service Requested Service. Should be one of the following: [transcription, translation]
source_language Languages in the audio file provided by the client. Should contain a language code, or a list of language codes. E.g. en, cn, or ['en', 'de', 'cn'].
target_language Desired target language, either for the transcription or the voice-over translation. Should contain a single language code.

Authentication

All requests must use HTTP basic auth using a username and password we provide.

Result

For any successful asynchronous request, we return a 202 Accepted response with no body.

Callback response

After completion of the demanded service, we POST a request to the callback_url.

Parameter Description
request_sid The unique identifier for this request
status Status message. Either ok, or error
message An empty string, or a message explaing the related status code.
transcription optional If requested, a document containing the transcription.
translation optional If requested, an audio file with voice-over translation of the original message.

Authentication

Our request uses HTTP basic auth with a username and password you provide.

Complete Sample Request


import requests

url = "https://cadencetranscription.herokuapp.com/api"

headers = {'X-Twilio-VendorAccountSid': 'AC05b3911315a1322d1dede66eed740000',
           'X-Twilio-Signature': '0FqS203W44/lM2UEM+51hRzwat4=',
           'X-Twilio-RequestSid': 'MR000009775bb6d43d1cabc4955723fae1',
           'X-Twilio-AddOnSid': 'XBc6dc06ce91d566fae284bc2bf36218a4',
           'X-Twilio-AddOnVersionSid': 'XC2ad3d7d6478a2ca72f224d817a241586',
           'X-Twilio-AddOnInstallSid': 'XDe2767c53b3d7be099a825252c6cf4e59',
           'X-Twilio-AddOnConfigurationSid': 'XEbee2b4cf26384f0b88ad98a25530c338',
            }

data = {'source_language': ['en','de'],
        'target_language': 'cn',
        'request_sid': 'MR000009775bb6d43d1cabc4955723fae1',
        'requested_service': 'transcription',
        'callback_url': 'http://httpbin.org/post',
        'channels': 2,
        'duration': 6000, # in milliseconds
        'format': 'audio/x-wav',
        'media_sid': 'WcS42767c53b3d7be099a825252c6c123e59',
        'size': 1204, # in bytes
        }

auth = ('cadence', 'friend')

audio_file = open('file.wav', 'rb')
files = {'audio_data': audio_file}

r = requests.post(url, auth=auth, files=files, data=data, headers=headers)

assert r.status_code == 202
assert not r.content

curl  -X POST \
 -u cadence:friend \
 --header 'X-Twilio-VendorAccountSid:AC05b3911315a1322d1dede66eed740000' \
 --header 'X-Twilio-Signature:0FqS203W44/lM2UEM+51hRzwat4=' \
 --header 'X-Twilio-RequestSid:MR000009775bb6d43d1cabc4955723fae1' \
 --header 'X-Twilio-AddOnSid:XBc6dc06ce91d566fae284bc2bf36218a4' \
 --header 'X-Twilio-AddOnVersionSid:XC2ad3d7d6478a2ca72f224d817a241586' \
 --header 'X-Twilio-AddOnInstallSid:XDe2767c53b3d7be099a825252c6cf4e59' \
 --header 'X-Twilio-AddOnConfigurationSid:XEbee2b4cf26384f0b88ad98a25530c338' \
 --form source_language="en" \
 --form source_language="de" \
 --form target_language=cn \
 --form request_sid=MR000009775bb6d43d1cabc4955723fae1 \
 --form requested_service=transcription \
 --form callback_url="http://httpbin.org/post" \
 --form channels=2 \
 --form duration=6000 \
 --form format="audio/x-wav" \
 --form media_sid="WcS42767c53b3d7be099a825252c6c123e59" \
 --form size=1204 \
 --form "audio_data=@file.wav" \
 https://cadencetranscription.herokuapp.com/api

Complete Sample Response


import requests

callback_url = 'http://httpbin.org/post'

headers = {'user-agent': 'cadencetranscription/v/0.1'}

data = {
    'request_sid': 'MR000009775bb6d43d1cabc4955723fae1',
    'status': 'ok',
    'message': '',
}

auth = ('cadence', 'friend')

audio_file = open('file.wav', 'rb')
transcription_file = open('transcription.pdf', 'rb')

files = {'transcription': transcription_file,
         'translation': audio_file}

r = requests.post(url, auth=auth, files=files, data=data, headers=headers)
curl  -X POST \
 -u cadence:friend \
 --header 'user-agent:cadencetranscription/v/0.1' \
 --form status=ok \
 --form message="" \
 --form request_sid=MR000009775bb6d43d1cabc4955723fae1 \
 --form "transcription=@transcription.pdf" \
 --form "translation=@file.wav" \
 http://httpbin.org/post