Jobs

Get Job By Id

Returns information about a transcription job

SecurityAccessToken
Request
path Parameters
id
required
string

Rev AI API Job Id

Responses
200

Transcription Job Details

401

Request Unauthorized

404

Job Not Found

get/jobs/{id}
Request samples
curl -X GET "https://api.rev.ai/speechtotext/v1/jobs/{id}" -H "Authorization: Bearer $REV_ACCESS_TOKEN"
Response samples
application/json
{
  • "id": "Umx5c6F7pH7r",
  • "status": "in_progress",
  • "language": "en",
  • "created_on": "2018-05-05T23:23:22.29Z",
  • "transcriber": "machine"
}

Delete Job by Id

Deletes a transcription job. All data related to the job, such as input media and transcript, will be permanently deleted. A job can only be deleted once it's completed (either with success or failure).

SecurityAccessToken
Request
path Parameters
id
required
string

Rev AI API Job Id

Responses
204

Job was successfully deleted

401

Request Unauthorized

404

Job Not Found

409

Conflict

delete/jobs/{id}
Request samples
curl -X DELETE "https://api.rev.ai/speechtotext/v1/jobs/{id}" -H "Authorization: Bearer $REV_ACCESS_TOKEN"
Response samples
application/problem+json
{
  • "title": "Authorization has been denied for this request",
  • "status": 401
}

Get List of Jobs

Gets a list of transcription jobs submitted within the last 30 days in reverse chronological order up to the provided limit number of jobs per call. Note: Jobs older than 30 days will not be listed. Pagination is supported via passing the last job id from a previous call into starting_after.

SecurityAccessToken
Request
query Parameters
limit
integer or null [ 0 .. 1000 ]
Default: 100

Limits the number of jobs returned, default is 100, max is 1000

starting_after
string or null

If specified, returns jobs submitted before the job with this id, exclusive (job with this id is not included)

Responses
200

List of Rev AI Transcription Jobs

400

Bad Request

401

Request Unauthorized

get/jobs
Request samples
# Get list of jobs with a limit of 10 jobs
curl -X GET "https://api.rev.ai/speechtotext/v1/jobs?limit=10" -H "Authorization: Bearer $REV_ACCESS_TOKEN"

# Get list of jobs starting after (submitted before) job with id Umx5c6F7pH7r
curl -X GET "https://api.rev.ai/speechtotext/v1/jobs?starting_after=Umx5c6F7pH7r" -H "Authorization: Bearer $REV_ACCESS_TOKEN"
Response samples
application/json
[
  • {
    }
]

Submit Transcription Job

Starts an asynchronous job to transcribe speech-to-text for a media file. Media files can be specified in two ways, either by including a public url to the media in the transcription job options or by uploading a local file as part of a multipart/form request.

SecurityAccessToken
Request
Request Body schema:

Transcription Job Options

media_url
string <= 2048 characters
Deprecated

Deprecated. Use source_config instead. Direct download media url. Ignored if submitting job from file. Note: Media files longer than 17 hours are not supported for English transcription. Media files longer than 6 hours are not supported for non-English transcription with languages codes fa, he, id, ta and te. The other non-English language codes support media files with duration up to 12 hours. For non-English jobs, expected turnaround time can be up to 6 hours. If this parameter is used to pass in the media url, the media url will be visible in the response. It is recommended to use the source_config parameter instead, as authorization headers can be included and both the media url and auth headers will be encrypted when stored.

object or null

Contains the direct download media url in addition to optional authorization headers, if they are needed to access the file. Ignored if submitting job from file. Only one of source_config and media_url may be set. This option will not be visible in the submission response.

metadata
string or null <= 512 characters

Optional metadata that was provided during job submission.

callback_url
string or null <= 1024 characters
Deprecated

Callback url provided by the user.

object or null

Optional configuration for a callback url to invoke when processing is complete, in addition to auth headers if they are needed to invoke the callback url. Cannot be set if callback_url is set. This option will not be visible in the submission response.

transcriber
string or null
Default: "machine"

User-supplied transcriber to transcribe the audio file.

Enum: "machine" "human" "machine_v2"
verbatim
boolean or null (VerbatimField)
Default: false

Only available for human transcriber option When this field is set to true the transcriber will transcribe every syllable. This will include all false starts, and disfluencies in the transcript.

rush
boolean or null (RushField)
Default: false

Only available for human transcriber option When this field is set to true your job is given higher priority and will be worked on sooner by our human transcribers.

test_mode
boolean or null (TestModeField)
Default: false

Only available for human transcriber option When this field is set to true the behavior will mock a normal human transcription job except no transcription will happen. The primary use case is to test integrations without being charged for human transcription.

Array of objects or null (SegmentsToTranscribeField)

Only available for human transcriber option. Use this option to specify which sections of the transcript need to be transcribed. Segments must be at least two minutes in length and cannot overlap.

skip_diarization
boolean or null
Default: false

Specify if speaker diarization will be skipped by the speech engine

skip_punctuation
boolean or null
Default: false

Specify if "punct" type elements will be skipped by the speech engine. For JSON outputs, this includes removing spaces. For text outputs, words will still be delimited by a space

remove_disfluencies
boolean or null
Default: false

Currently we only define disfluencies as 'ums' and 'uhs'. When set to true, disfluencies will be not appear in the transcript.

filter_profanity
boolean or null
Default: false

Enabling this option will filter for approx. 600 profanities, which cover most use cases. If a transcribed word matches a word on this list, then all the characters of that word will be replaced by asterisks except for the first and last character.

speaker_channels_count
integer or null [ 1 .. 8 ]

User-supplied number of speaker channels in the audio.

delete_after_seconds
integer or null [ 0 .. 2592000 ]

Amount of time after job completion when job is auto-deleted. Present only when preference set in job request.

custom_vocabulary_id
string or null

User-supplied custom vocabulary ID to be used with job for transcription.

Array of objects [ 1 .. 50 ] items

Specify a collection of custom vocabulary to be used for this job. Custom vocabulary informs and biases the speech recognition to find those phrases (at the cost of slightly slower transcription).

language
string or null
Default: "en"

User-supplied language to transcribe the audio into.

Enum: "en" "ar" "bg" "ca" "cmn" "cs" "da" "de" "el" "es" "fa" "fi" "fr" "he" "hi" "hr" "hu" "id" "it" "ja" "ko" "lt" "lv" "ms" "nl" "no" "pl" "pt" "ro" "ru" "sk" "sl" "sv" "ta" "te" "tr"
Responses
200

Transcription Job Details

400

Bad Request

401

Request Unauthorized

413

Payload Too Large


Only returned when job is submitted using a local file as part of multipart/form-data. Submit a job with the source_config parameter for files larger than 2GBs

post/jobs
Request samples
{
  • "metadata": "example metadata",
  • "notification_config": {},
  • "source_config": {},
  • "transcriber": "machine",
  • "skip_diarization": false,
  • "skip_punctuation": false,
  • "remove_disfluencies": false,
  • "filter_profanity": false,
  • "speaker_channel_count": 1,
  • "delete_after_seconds": 2592000,
  • "custom_vocabulary_id": "cvgnDwmB6iXevn",
  • "language": "en"
}
Response samples
application/json
{
  • "id": "Umx5c6F7pH7r",
  • "status": "in_progress",
  • "language": "en",
  • "created_on": "2018-05-05T23:23:22.29Z",
  • "transcriber": "machine"
}

Transcripts

Get Transcript By Id

Returns the transcript for a completed transcription job. Transcript can be returned as either JSON or plaintext format. Transcript output format can be specified in the Accept header. Returns JSON by default.


Note: For streaming jobs, transient failure of our storage during a live session may prevent the final hypothesis elements from saving properly, resulting in an incomplete transcript. This is rare, but not impossible. To guarantee 100% completeness, we recommend capturing all final hypothesis when you receive them on the client.

SecurityAccessToken
Request
path Parameters
id
required
string

Rev AI API Job Id

header Parameters
Accept
string

MIME type specifying the transcription output format

Enum: "application/vnd.rev.transcript.v1.0+json" "text/plain"
Responses
200

Rev AI API Transcript


Note: Transcript output format is required in the Accept header. Output can either be in Rev's JSON format or plaintext.

401

Request Unauthorized

404

Job Not Found

406

Invalid Transcript Format

409

Conflict

get/jobs/{id}/transcript
Request samples
curl -X GET "https://api.rev.ai/speechtotext/v1/jobs/{id}/transcript" -H "Authorization: Bearer $REV_ACCESS_TOKEN" -H "Accept: application/vnd.rev.transcript.v1.0+json"
Response samples
{
  • "monologues": [
    ]
}

Captions

Get Captions

Returns the caption output for a transcription job. We currently support SubRip (SRT) and Web Video Text Tracks (VTT) output. Caption output format can be specified in the Accept header. Returns SRT by default.


Note: For streaming jobs, transient failure of our storage during a live session may prevent the final hypothesis elements from saving properly, resulting in an incomplete caption file. This is rare, but not impossible.

SecurityAccessToken
Request
path Parameters
id
required
string

Rev AI API Job Id

query Parameters
speaker_channel
integer

Identifies which channel of the job output to caption. Default is null which works only for jobs with no speaker_channels_count provided during job submission.

header Parameters
Accept
string

MIME type specifying the caption output format

Enum: "application/x-subrip" "text/vtt"
Responses
200

Rev AI API Captions


Note: Caption output format is required in the Accept header. The supported headers are application/x-subrip and text/vtt. (SRT)

401

Request Unauthorized

404

Job Not Found

405

Invalid Job Property

406

Invalid Caption Format

409

Conflict

get/jobs/{id}/captions
Request samples
curl -X GET "https://api.rev.ai/speechtotext/v1/jobs/{id}/captions" -H "Authorization: Bearer $REV_ACCESS_TOKEN" -H "Accept: application/x-subrip"
Response samples
1
00:00:01,210 --> 00:00:04,840
Hello there, this is a example captions output

2
00:00:07,350 --> 00:00:10,970
Each caption group is in the SubRip Text
file format

Accounts

Get Account

Get the developer's account information

SecurityAccessToken
Responses
200

Rev AI Account

401

Request Unauthorized

get/account
Request samples
curl -X GET "https://api.rev.ai/speechtotext/v1/account" -H "Authorization: Bearer $REV_ACCESS_TOKEN"
Response samples
application/json
{
  • "email": "jay@rev.ai",
  • "balance_seconds": 150
}