Temi Api

Documentation is a work in progress and subject to change.

Base URL and Versioning

The base URL for the API is https://api.temi.com/[version]. The current version is v1, thus the base URL for the current API version is https://api.temi.com/v1.

URLs for the endpoints described in the rest of this document are specified relative to the base URL above.

New versions of the API will be added only for backwards-incompatible changes, such as a new required field for a POST endpoint.

Backwards-compatible changes (e.g. new fields in responses) can be added without changing the version. Such changes will be noted in the release notes below.

Authorization

All operations must be authorized with an API key via a Bearer Authorization header. You can generate an API key by logging into your Temi account and going to the developer page.

API Key

Header:
Authorization: Bearer <Api Key>

curl -H “Authorization: Bearer <Api Key>”

Sample Unauthorized Response

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

Jobs Operations

All dates are in standard ISO-8601 UTC form unless stated otherwise.
Eg. 2018-05-05T23:23:22.29Z

Job Object

job {
    id //id of this job. Eg. sd233343.
    status //current status of the job: in_progress, transcribed, failed
    created_on //the time when the job was created
    callback_url //the url that will be called when the job completes
    web_url //the url to the editor, allows to edit the transcript
    duration_seconds //duration of the file, null when not available
    name //name of the file provided (as temi shows), null when not available
    metadata //metadata provided when the job was submitted
    failure //failure reason ("unspecified", "download_failure", "insufficient_balance" or "invalid_media")
    failure_detail //human readable reason why the job failed
    last_modified_on //the time when the job was last modified in the editor
}

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
/jobs

Body:

Application/Json - Requires options (must set options.media_url property)

Multipart/Form-Data - Requires media file part in as form data and accepts optional options json (ignores options.media_url property) part

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 parameters were incorrect

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/invalid-parameters the api method is invoked with invalid parameters
https://www.temi.com/api/v1/errors/unsupported-media-content-type submitted media type is incorrect
https://www.temi.com/api/v1/errors/media-missing-filename media is uploaded as a part of multipart upload and the file name is not specified

403 when the submission failed due to insufficient account balance

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/out-of-credit you don’t have enough account balance to place the order

Usages:

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

Options Object

options
{
    media_url? //optional url to retrieve media to transcribe (1024 char limit). Ignored if the media is included as multipart data within the submit job 
    callback_url? // optional url to be invoked when the job completes the execution
    metadata? //optional metadata associated with the job (256 char limit)
}

Sample Response:

{
    "id": "sd11111",
    "status": "in_progress",
    "created_on": "2018-05-05T23:23:22.29Z",
}

Get Job Status

GET
/jobs/<id>

Returns:
job

400 invalid parameters

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/invalid-parameters the api method is invoked with invalid parameters

404 if job not found

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/job-not-found could not locate the job

Usage:

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

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
/jobs?limit=<100>&starting_after=<id?> -H “Authorization: Bearer <Api Key>”

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

400 - Invalid parameters

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/invalid-parameters the api method is invoked with invalid parameters

Usage:

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

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": "download_failure",
    "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
/jobs/<id>

Returns:
Status Code: 204

400 - invalid parameters

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/invalid-parameters the api method is invoked with invalid parameters

404 - if job is not found,

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/job-not-found could not locate the job

409 if it is not transcribed yet

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/invalid-job-state could not delete the job in this state

Usage:

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

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
                ts //the timestamp of the beginning of the element relative to the beginning of the audio
                end_ts // the timestamp of the end of the element relative to the beginning of the audio
                }
            ]
        }
    ] 
}

Get Transcript

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

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

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

400 - invalid parameters

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/invalid-parameters the api method is invoked with invalid parameters

409 - incorrect state

Possible problem details types:

Problem details type Description
https://www.temi.com/api/v1/errors/invalid-job-state the job is in invalid state to obtain the transcript

Usages:

text/plain

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

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://api.temi.com/v1/jobs/<id>/transcript?version=latest -H "Accept: application/json" -H "Authorization: Bearer <Api Key>"

Sample Response:

{
    "speakers": [{
        "id": 0,
        "name": "Speaker 1"
    }],
    "monologues": [{
        "id": 0,
        "speaker": 0,
        "speaker_name": "Speaker 1",
        "elements": [
        {
            "type": "text",
            "value": "Hi",
            "ts": 33.83,
            "end_ts": 33.92,
        },
        {
            "type": "text",
            "value": "there",
            "ts": 33.94,
            "end_ts": 34.49 
        }]
    }
}         

Account Operations

You can add to your API balance on the settings page.

Get Account Balance

GET
/account

Returns:

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

Usage:

curl -XGET -i https://api.temi.com/v1/account -H "Authorization: Bearer <Api Key>"

Sample Response

{ 
    balance: 1000.00
}

Webhooks

It is possible to provide callback_url field during job submission. If the url is provided the API will POST to this url when the job either transcribes or fails.

The payload of the POST request will contain the Job Object for the transcribed or failed job in the following JSON structure:

{ 
  job: <Job Object>
}

Example:

{ 
  job: {
    "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",
    "callback_url": "https://callback.example.com/callback"
  }
}

Error messages structure

When an error occurs, the API reports additional problem details information within the error HTTP response payload. The information is designed to help to diagnose what went wrong with the call and adjust the calling code accordingly.

The problem details information is represented as a Json object with the following optional properties:

Property Description
type a URI representing the type for the error
title a short human readable description of type
detail additional details of the error

In addition to the properties listed above, the problem details object might list additional properties that should help to troubleshoot the problem. For example when the API detects incorrectly formatted parameters, the problem details object would have additional parameters property that will list invalid parameters with a short description explaining what is incorrect.

RFC7807 describes the problem details object more thoroughly.

Besides the base properties, some error types might have additional properties specific for the error.

https://www.temi.com/api/v1/errors/invalid-parameters

Property Description
parameters lists parameters that have problems and the errors encountered for them
{
   "parameters": {
    "options.media_url": [
      "The media_url field is required."
    ]
  },
  "type": "https:\/\/www.temi.com\/api\/v1\/errors\/invalid-parameters",
  "title": "Your request parameters didn't validate"
}

https://www.temi.com/api/v1/errors/unsupported-media-content-type

Property Description
allowed_values lists allowed values
current_value the value that was provided
{
  "allowed_values": [
    "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\/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"
  ],
  "current_value": "text\/plain",
  "type": "https:\/\/www.temi.com\/api\/v1\/errors\/unsupported-media-content-type",
  "title": "Not supported media content type",
  "detail": "text\/plain is not supported content type for the media"
}

https://www.temi.com/api/v1/errors/media-missing-filename

{
  "type": "https:\/\/www.temi.com\/api\/v1\/errors\/media-missing-filename",
  "title": "filename is required for media part"
}

https://www.temi.com/api/v1/errors/out-of-credit

Property Description
current_balance Shows the current account balance in USD
{
    "current_balance": 0.00,
    "type": "https://www.temi.com/api/v1/errors/out-of-credit",
    "title": "You do not have enough credit.",
    "detail": "You have only $0.00"
}

https://www.temi.com/api/v1/errors/job-not-found

{
  "type": "https:\/\/www.temi.com\/api\/v1\/errors\/job-not-found",
  "title": "could not find job"
}

https://www.temi.com/api/v1/errors/invalid-job-state

Property Description
allowed_values lists allowed states
current_value the current state
{
  "allowed_values": [
    "failed",
    "transcribed"
  ],
  "current_value": "in_progress",
  "type": "https:\/\/www.temi.com\/api\/v1\/errors\/invalid-job-state",
  "title": "Job is in invalid state",
  "detail": "Job is in invalid state to be deleted"
}