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_type s, 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