NAV Navbar
Jotengine
shell

Introduction

Welcome to the Jotengine API! Use this API to textify your audio or add captions to videos. You can get started right away by signing up and grabbing an API key in your api settings page.

Topics

Getting started

Getting an API key

To start using the API, register an account at jotengine.com and grab an API key in your api settings page.

Creating a file

Example request

curl https://jotengine.com/api/v1/files \
  -d '{"url": "http://example.com/example.mp3"}' \
  -u api_key:

Once you have your API key, you can make your first request by creating a file object.

Example response

{
  "id": "AlUAVmYAbww5rprF7Fi2g",
  "status": "created"
}

Checking the status of a file

Example file status

{
  "id": "AlUAVmYAbww5rprF7Fi2g",
  "url": "https://example.com/files/AlUAVmYAbww5rprF7Fi2g/example.mp4",
  "name": "example.mp4",
  "duration": 237.0,
  "status": "ready",
  "estimates": {"caption": 1.98, "transcript": 5.93}
}

Example webhook request

{
  "file": {
    "id": "AlUAVmYAbww5rprF7Fi2g",
    "status": "processing"
  }
}

Before starting a job, the file may take a few moments to be downloaded and processed to validate the right file type and duration. To check the status of a file, you may either provide a webhook to be notified when a file is ready to transcribe or caption, or you may poll the file object via the api/v1/files endpoint.

Starting a job

Example request

curl https://jotengine.com/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "AlUAVmYAbww5rprF7Fi2g",
    "text_type": "transcript"
   }' \
  -u api_key:

Example response

{
  "job": {
    "id": "jdBd9dQltxF_BmTQMSjc1g",
    "file_id": "AlUAVmYAbww5rprF7Fi2g",
    "text_type": "transcript",
    "status": "processing"
  }
}

With a file_id in hand and your billing details in place, you can create a job to transcribe or caption your file.

Checking the status of a job

Example webhook request

{
  "job": {
    "id": "NoIj79aNNztyDh7tsn42RA",
    "status": "completed"
  }
}

Example job request

curl https://jotengine.com/api/v1/jobs/NoIj79aNNztyDh7tsn42RA \
  -u api_key:

Example response

{
  "job": {
    "id": "jdBd9dQltxF_BmTQMSjc1g",
    "file_id": "AlUAVmYAbww5rprF7Fi2g",
    "text_type": "transcript",
    "status": "processing"
  }
}

Jobs can be tracked either from the webhook provided in your settings page, or through polling the job object via the api/v1/jobs.

Retrieving results

Example request

curl https://jotengine.com/api/v1/jobs/NoIj79aNNztyDh7tsn42RA \
  -u api_key:

Example response

{
  "job": {
    "id": "jdBd9dQltxF_BmTQMSjc1g",
    "file_id": "AlUAVmYAbww5rprF7Fi2g",
    "text_type": "transcript",
    "status": "completed"
  }
}

Once complete, you may retrieve results through the job’s /results API endpoint, which can be requested in different formats.

Authentication

To authorize your requests, append your requests with the -u flag and your api key:

curl api_endpoint \
  -u api_key:

Make sure to replace api_key with your API key and to include the colon at the end.

Jotengine uses API keys to authorize access to the API with HTTP basic authentication. Basic authorization follows this header format, where the api_key is base64 encoded (note the extra colon ‘:’):

Authorization: Basic Base64(api_key:)

All endpoints use TLS/SSL, so be sure to send requests using the HTTPS protocol.

Webhooks

Example request

{
  "job": {
    "id": "NoIj79aNNztyDh7tsn42RA",
    "status": "completed"
  }
}

We use webhooks to inform you of status changes to your files or your jobs.

Add a webhook address to your api settings page to receive these messages.

Webhook authorization

Webhook requests also include token authorization headers using your API key to differentiate the traffic from non-Jotengine sources.

Authorization: Token token="api_key"

Errors

The Jotengine API uses the following HTTP codes:

HTTP Status Description
200 – OK Everything worked as expected!
400 – Bad Request Your request was missing some important things.
401 – Unauthorized Your API key is wrong or you may be trying to access someone else’s stuff.
404 – Not Found We couldn’t find what you were looking for.
429 – Too Many Requests You’re talking a bit too fast (sending too many requests too quickly)! Try slowing down your request rate.
500 – Server Error Something went wrong on our end.

Along with the http error code, we provide a description of the error.

Example response

{
  "errors": [
    "Job was missing a file_id.",
    "Job was missing a text_type ('transcript' or 'caption')."
  ]
}

Transcripts and captions

The Jotengine API lets you request two different types of jobs.

Captions contain timestamped text of what’s being said in 3 to 5 second increments and are typically used to subtitle videos. Transcripts are like captions, but with 10 to 20 second increments and include speaker names.

Billing and pricing

To create a transcription or caption job, you must provide your billing information in advance. To add your details, please go to the billing settings page for your account. You will not be charged until the job is completed.

Transcription and caption rates

Jobs are charged in seconds, rounded to the nearest second.

Text type Rate
Transcript $1.50 / minute
Caption $0.50 / minute

Resources

Files

The file object

Example file object

{
  "file": {
    "id": "AlUAVmYAbww5rprF7Fi2g",
    "url": "http://example.com/files/AlUAVmYAbww5rprF7Fi2g/example.mp4",
    "name": "example.mp4",
    "duration": 237.0,
    "status": "ready",
    "estimates": {"caption": 1.98, "transcript": 5.93}
  }
}

Files are either audio or video files to be captioned or transcribed. Files can be up to 256MB in size.

To send a file to the API, provide a location to the file as a URL - e.g. from Amazon S3 or Dropbox. The API does not yet support direct uploads.

We support most audio and video formats. Examples include 3GP, AAC, AVI, FLV, MP3, MP4 and MPEG-2. If you run into any issues, please let us know at contact@jotengine.com.

File attributes

Attribute Type Description
id string -
url string The URL to access this file
name string File name
duration float Duration of file in seconds
status string The status of this file
estimates object Estimates for different job text_types, in dollars

File statuses

Status Description
created File object created
processing File being processed to validate file type and to record meta data (duration, file size)
ready Ready to be transcribed or captioned
unprocessable Unprocessable file format

Create a file

Example request

curl https://jotengine.com/api/v1/files \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://dropbox.com/s/dropboxsharetoken/example.mp4"
  }' \
  -u api_key:

Example response

{
  "id": "AlUAVmYAbww5rprF7Fi2g",
  "status": "created"
}

POST https://jotengine.com/api/v1/files

Create a file using a predefined URL (e.g. Amazon S3, Dropbox, YouTube, Vimeo, etc… ). Status updates will be sent to a webhook URL if provided in the account page.

Please remember to set the content-type to json when sending data!

Retrieve a file

GET https://jotengine.com/api/v1/files/:id

Example request

curl https://jotengine.com/api/v1/files/AlUAVmYAbww5rprF7Fi2g \
  -u api_key:

Example response

{
  "id": "AlUAVmYAbww5rprF7Fi2g",
  "url": "http://example.com/files/AlUAVmYAbww5rprF7Fi2g/example.mp4",
  "name": "example.mp4",
  "duration": 237.0,
  "status": "ready"
}

Retrieve a specific file using this endpoint:

List all files

Example request

curl https://jotengine.com/api/v1/files \
  -u api_key:

Example response

{
  "files": [
    {
      "id": "AlUAVmYAbww5rprF7Fi2g",
      "url": "http://example.com/files/AlUAVmYAbww5rprF7Fi2g/example.mp4",
      "name": "example.mp4",
      "duration": 237.0,
      "status": "ready"
    }
  ]
}

Get a list of your files by with this endpoint:

GET https://jotengine.com/api/v1/files

Jobs

The job object

Jobs manage the process of transcribing a specific file. You can create, cancel, or monitor the status of a job.

Jobs and files are currently one to one. Creating a job with the same file will return a job already created for that file object.

Job attributes

Attribute Type Description
id string
file_id (required) string File ID to be transcribed or captioned
text_type (required) string Request either a transcript or a caption
status string Status of job

Text types

Request either a transcript or caption by setting text_type to transcript or caption.

Job statuses

Example job

{
  "job": {
    "id": "jdBd9dQltxF_BmTQMSjc1g",
    "file_id": "AlUAVmYAbww5rprF7Fi2g",
    "text_type": "transcript",
    "status": "completed"
  }
}
Status Description
processing The associated file is being prepared for transcribing or captioning
transcribing The file is being transcribed
completed Transcription is completed
canceled Job has been canceled. All further work is stopped.
failed The transcription wasn’t able to be transcribed

Create a job

Example request

curl https://jotengine.com/api/v1/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "AlUAVmYAbww5rprF7Fi2g",
    "text_type": "transcript"
   }' \
  -u api_key:

Example response

{
  "job": {
    "id": "jdBd9dQltxF_BmTQMSjc1g",
    "file_id": "AlUAVmYAbww5rprF7Fi2g",
    "text_type": "transcript",
    "status": "processing"
  }
}

POST https://jotengine.com/api/v1/jobs

Create a job to transcribe a file.

Jobs are started immediately upon creation. They can only be canceled during the processing phase. Please remember to set the content-type to json when sending data!

Retrieve a job

Example request

curl https://jotengine.com/api/v1/jobs/jdBd9dQltxF_BmTQMSjc1g \
  -u api_key:

Example response

{
  "job": {
    "id": "jdBd9dQltxF_BmTQMSjc1g",
    "file_id": "AlUAVmYAbww5rprF7Fi2g",
    "text_type": "transcript",
    "status": "completed"
  }
}

GET https://jotengine.com/api/v1/jobs/:id

This endpoint retrieves a specific job.

Retrieve results

Example request

curl https://jotengine.com/api/v1/jobs/jdBd9dQltxF_BmTQMSjc1g/results?file_type=json \
  -u api_key:

Example response

[
  {
    "start_time": 0.54,
    "end_time": 2.77,
    "duration": 2.23,
    "speaker": "Alice",
    "text": "Let's get started"
  },
  {
    "start_time": 4.43,
    "end_time": 6.39,
    "duration": 1.96,
    "speaker": "Bob",
    "text": "Sure thing"
  }
]

GET https://jotengine.com/api/v1/jobs/:id/results?file_type=:file_type

This endpoint retrieves results for a completed job. Add an optional file_type param to request different formats. Default is json.

file_type Description
json JSON formatted array of text segments
txt Text format of transcript
md Markdown format
docx Word format
srt SubRip format (commonly used for captions)

Cancel a job

  curl https://jotengine.com/api/v1/jobs/jdBd9dQltxF_BmTQMSjc1g \
    -H "Content-Type: application/json" \
    -d '{
      "job": {
        "status": "canceled"
      }
    }'
    -u api_key:

POST https://jotengine.com/api/v1/jobs/:id/cancel

Jobs can be canceled during the processing state by sending a POST request to the job’s /cancel endpoint.

Restart a job

Example request

  curl https://jotengine.com/api/v1/jobs/jdBd9dQltxF_BmTQMSjc1g \
    -H "Content-Type: application/json" \
    -d '{
      "job": {
        "status": "restarted"
      }
    }'
    -u api_key:

Example response

{
  "job": {
    "id": "jdBd9dQltxF_BmTQMSjc1g",
    "file_id": "AlUAVmYAbww5rprF7Fi2g",
    "text_type": "transcript",
    "status": "processing"
  }
}

POST https://jotengine.com/api/v1/jobs/:id/restart

Jobs can be restarted during the canceled state by sending a POST request to the job’s restart endpoint.

List all jobs

Example request

curl https://jotengine.com/api/v1/jobs \
  -u api_key:

Example response

{
  "jobs": [
    {
      "id": "jdBd9dQltxF_BmTQMSjc1g",
      "file_id": "AlUAVmYAbww5rprF7Fi2g",
      "text_type": "transcript",
      "status": "processing"
    },
    {
      "id": "Qimz_ZlafS4YUL-cksji-w",
      "file_id": "VaeP4flPUXiF3QJ3ogx5FQ",
      "text_type": "caption",
      "status": "completed"
    }
  ]

}

Retrieve a list of your jobs using the jobs endpoint.

GET https://jotengine.com/api/v1/jobs