Documentation is a work in progress and subject to change.
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.
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.
Header:
Authorization: Bearer <Api Key>
curl -H “Authorization: Bearer <Api Key>”
Sample Unauthorized Response
{
"message": "Authorization has been denied for this request."
}
All dates are in standard ISO-8601 UTC form unless stated otherwise.
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
}
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
{
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
/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"
}
GET
/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)
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
/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 job 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>"
[Speaker] [Monologue Start Time] [Monologue Text]
\n
[Speaker] [Monologue Start Time] [Monologue Text]
\n
...
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
/jobs/<id>/transcript?version=[latest(default), machine]
Query string:
version: (latest, machine) - the latest version includes all changes made in the Temi editor, while the machine version is the original transcript produced by the Temi API. Defaults to latest version if none is provided.
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 |
| https://www.temi.com/api/v1/errors/unsupported-transcript-format | submitted transcript format is not supported |
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
}]
}
}
POST
/jobs/<id>/share
Returns:
{
editor_url // transcript editor url with full permissions
}
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 |
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 share the transcript editor url |
Usage:
curl -XPOST -i https://api.temi.com/v1/jobs/<id>/share -H "Authorization: Bearer <Api Key>"
Sample Response:
{
"editor_url": "https://www.temi.com/editor/t/123456"
}
You can add to your API balance on the settings page.
GET
/account
Returns:
{
balance, //account balance down to whole cents (ie. 150.00)
email //account email
}
Usage:
curl -XGET -i https://api.temi.com/v1/account -H "Authorization: Bearer <Api Key>"
Sample Response
{
"balance" : 1000.00,
"email" : "customer@example.com"
}
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"
}
}
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.
| 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"
}
| 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"
}
{
"type": "https:\/\/www.temi.com\/api\/v1\/errors\/media-missing-filename",
"title": "filename is required for media part"
}
| 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"
}
{
"type": "https:\/\/www.temi.com\/api\/v1\/errors\/job-not-found",
"title": "could not find job"
}
| 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"
}
| Property | Description |
|---|---|
| allowed_values | lists allowed values |
{
"allowed_values": [
"text/plain",
"application/json",
"application/msword",
"application/pdf"
],
"type": "https://www.temi.com/api/v1/errors/unsupported-transcript-format",
"title": "Transcript format is not supported",
"detail": "Unsupported value application/ecmascript"
}