Temi Api

Documentation is a work in progress and subject to change.

Authorization

All operations must be authorized with an Access Token via a Bearer Authorization header.

Access Token

Header:
Authorization: Bearer <Access Token>

curl -H “Authorization: Bearer <Access Token>”

Sample Unauthorized Response

{
    "message": "Authorization has been denied for this request."
}

Jobs Operations

Job Object

job {
    id //id of this job. Eg. sd233343.
    status //current status of the job: inprogress, transcribed, failed
    created_on //the time when the job was created
    web_url //the url to the editor if job is transcribed, allows to edit the transcript
    duration_seconds //duration of the file, null when not available
    name //name of the file provided (as temi shows)
    metadata //metadata provided when the job was submitted, null if not provided
    failure //failure reason ("unspecified", "sourceDownload", or "transcription"). This and failure_detail are null if job status is not failed
    failure_detail //human readable reason why the job failed
    last_modified_on //the time when the job was last modified in the editor. Null if transcript was never modified
}

Note: properties will not be displayed in the returned job object if they are null


Submit job

A job can be submitted via either a URL passed in via the options object or via binary data passed in as a multipart/form-data

Headers:
Content-Type: (application/json, multipart/form-data)

POST
/api/v1/jobs

Body:

Application/Json - Requires options (must set media_url property in the options json)

Multipart/Form-Data - Requires options json (cannot set media_url property in the options json) and media file pass in as form data

Accepted Media Types

//audio
"audio/wav"
"audio/mpeg"
"audio/mpeg3"
"audio/mp3"
"audio/x-mpeg-3"
"audio/x-aiff"
"audio/x-aifc"
"audio/x-wav"
"audio/x-realaudio"
"audio/mp4"
"audio/mp4a"
"audio/mp4a-latm"
"audio/webm"
"audio/ogg"
"audio/vorbis"
"audio/vnd.wave"

//video
"video/x-msvideo"
"video/avi"
"video/msvideo"
"video/mpeg"
"video/mp4"
"video/x-mpeg"
"video/x-m4v"
"video/quicktime"
"video/ogg"
"video/webm"
"video/x-matroska"
"video/x-ms-wmv"
"video/x-flv"

Returns: job

400 when the submission is invalid

Usages:

 curl -XPOST -i https://www.temi.com/api/v1/jobs -H "Content-Type: application/json" -d '{"media_url": "https://www.youtube.com/watch?v=xK2vinLqFzw"}' -H "Authorization: Bearer <Access Token>"
curl -i -XPOST https://www.temi.com/api/v1/jobs -F "options=@{\"metadata\":\"meta content\"}" -F "media=@sample_audio.m4a;type=audio/mpeg" -H "Authorization: Bearer <Access Token>"
curl -XPOST -i https://www.temi.com/api/v1/jobs -F "options=@options.json" -F "media=@sample_audio.mp3;type=audio/mpeg" -H "Authorization: Bearer <Access Token>"

Options Object

options
{
    media_url? //optional url to retrieve media to transcribe. Cannot be set when media in submit job is set (1024 char limit)
    metadata? //optional metadata associated with the job (256 char limit)
}

Sample Response:

{
    "id": "sd11111",
    "status": "transcribed",
    "created_on": "2018-05-05T23:23:22.29Z",
    "duration_seconds": 120,
    "name": "Sample Audio.mp3"
}

Get Job Status

GET
/api/v1/jobs/<id>

Returns:
job

404 if job not found

Usage:

curl -XGET -i https://www.temi.com/api/v1/jobs/<id> -H "Authorization: Bearer <Access Token>"

Sample Response:

{
    "id": "sd11111",
    "status": "transcribed",
    "created_on": "2018-05-05T23:23:22.29Z",
    "web_url": "https://www.temi.com/editor/file/123456",
    "duration_seconds": 120,
    "name": "Sample Audio.mp3"
}

List jobs

GET
/api/v1/jobs?limit=<100>&starting_after=<id?> -H “Authorization: Bearer <Access Token>”

Returns:
job[] - List of jobs sorted by descending order of date placed (latest first)

Usage:

curl -XGET -i https://www.temi.com/api/v1/jobs?limit=10 -H "Authorization: Bearer <Access Token>"

Sample Response:

[{
    "id": "sd11111",
    "status": "transcribed",
    "created_on": "2018-05-05T23:23:22.29Z",
    "web_url": "https://www.temi.com/editor/file/123456",
    "duration_seconds": 120,
    "name": "Sample Audio.mp3"
},
{
    "id": "sd11112",
    "status": "failed",
    "failure": "sourceDownload",
    "failure_detail": "Failed to download source file",
    "created_on": "2018-05-05T23:23:22.29Z",
    "duration_seconds": 100,
    "name": "Bad Audio.wav"
}]

Delete job

DELETE
/api/v1/jobs/<id>

Returns:
Status Code: 204

404 - if job is not found, 409 if it is not transcribed yet

Usage:

curl -XDELETE -i https://www.temi.com/api/v1/jobs/<id> -H "Authorization: Bearer <Access Token>"

Transcript Operations

Transcript Object

Transcript Format - text/plain
[Speaker]  [Monologue Start Time]  [Monologue Text]

\n

[Speaker]  [Monologue Start Time]  [Monologue Text]

\n

...
Transcript Format - application/json
transcript {
    speakers: [
        speaker {
            id //speaker Id,
            name //the name of the speaker as labeled in the transcript
        }
    ],
    monologues: [
        monologue { 
            id //monologue Id,
            speaker //id of the speaker of the monologue,
            speaker_name //name of the speaker
            elements: [
            element {  
                type //"text", "tag",
                value //text value of the element
                }
            ]
        }
    ] 
}

Get Transcript

GET
/api/v1/jobs/<id>/transcript?version=[latest(default), machine]

Header:
Accept: (text/plain, application/json) - determines the format of the returned transcript

Returns:
Transcript object - (latest or machine generated) with the Transcript Format specified in the Accept header

400 if the version is not supported

Usages:

text/plain

curl -XGET -i https://www.temi.com/api/v1/jobs/<id>/transcript?version=machine -H "Accept: text/plain" -H "Authorization: Bearer <Access Token>"

Sample Response:

Speaker 1:          00:00          Hello there, this is a sample transcript in plain text

Speaker 1:          00:43          It is in the format of <Speaker> <Timestamp> <Text>

application/json

curl -XGET -i https://www.temi.com/api/v1/jobs/<id>/transcript?version=latest -H "Accept: application/json" -H "Authorization: Bearer <Access Token>"

Sample Response:

{
    "speakers": [{
        "id": 0,
        "name": "Speaker 1"
    }],
    "monologues": [{
        "id": 0,
        "speaker": 0,
        "speaker_name": "Speaker 1",
        "elements": [
        {
            "type": "text",
            "value": "Hi"
        },
        {
            "type": "text",
            "value": "there"
        }]
    }
}         

Account Operations

Get Account Details

GET
/api/v1/account

Returns:

balance {
    balance //account balance down to whole cents (ie. 150.00)
}

Usage:

curl -XGET -i https://www.temi.com/api/v1/account -H "Authorization: Bearer <Access Token>"

Sample Response

{ 
    balance: 1000.00
}