Rev

Asynchronous Speech-To-Text API Documentation

Rev.ai provides quality speech-text recognition via a RESTful API. All public methods and objects are documented here for developer reference. For a real-time…

AI & machine learning#openapi#text

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Rev.ai provides quality speech-text recognition via a RESTful API. All public methods and objects are documented here for developer reference.
For a real-time speech to text solution, use Rev.ai's Streaming API.

Base Endpoint

The base url for this version of the API is

> https://api.rev.ai/speechtotext/v1

All endpoints described in this documentation are relative to this base url.

Quick Start

Follow the getting started checklist

Get your Access Token

You can generate your access token on the settings page of your account. This access token only needs to be generated once and never expires. You can re-generate your token, however this will invalidate the previous token.

Submit a File

To submit an audio file for transcription to Rev.ai:

curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" -H "Authorization: Bearer $REV_ACCESS_TOKEN" -H "Content-Type: application/json" -d "{\"media_url\":\"https://www.rev.ai/FTC_Sample_1.mp3\",\"metadata\":\"This is a sample submit jobs option\"}"

You’ll receive a response like this:

~~~
{
"id": "Umx5c6F7pH7r",
"created_on": "2018-09-15T05:14:38.13",
"name": "sample.mp3",
"metadata": "This is a sample submit jobs option for multipart",
"status": "in_progress"
}
~~~

The id (in this case Umx5c6F7pH7r) will allow you to retrieve your transcript.

Get Your Transcript

Once a transcription job's status becomes transcribed, you can retrieve the transcript in JSON format by running:

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"

Alternatively you can get the plain text version by running:

curl -X GET "https://api.rev.ai/speechtotext/v1/jobs/{id}/transcript" -H "Authorization: Bearer $REV_ACCESS_TOKEN" -H "Accept: text/plain"

You can poll for the status of your job by querying for the job periodically:

curl -X GET https://api.rev.ai/speechtotext/v1/jobs/{id} -H "Authorization: Bearer $REV_ACCESS_TOKEN"

Note: Polling is NOT recommended in a production server. Rather, use webhooks to asynchronously receive notifications once the transcription job completes

If you have any further questions, contact us at

Submitting Files

Two POST request formats can be used to submit a file: application/json or multipart/form-data.

JSON

This is the preferred method of file submission. Uses the media_url property to provide a direct download URL to the Rev.ai server.
This method supports the use of pre-signed URLs. Links to videos hosted on platforms like Youtube are not valid because they are not direct download links.

Important note on presigned URLs:
Signed URLs usually have an expiration time which is configurable. To ensure the Rev.ai server can access the link, make sure the expiration time is set to 2 hours or more.
In the event you plan on resending the same file, make sure to generate a new presigned URL.

FormData

Used to send a local file to the Rev.ai server. This allows the customer to send the file directly from the host machine.
Certain limits apply to this format, see the Async API Limits section for more detals.

Turnaround Time and Chunking

Often, especially for shorter files, your transcript will be ready in 5 minutes or less. It generally takes no longer than 15 minutes to return longer audios. If you require faster turn around time please contact

Chunking is the act of breaking audio files into smaller segments. Rev.ai uses this method to decrease turnaround time of audios greater than 3 minutes in length.

Webhooks

If the optional callback_url is provided, the API will make an HTTP POST request to the callback_url with the
following request body when the job either completes successfully or fails.

Sample Webhook

On Successful Transcription Job

{
  "job": {
    "id": "Umx5c6F7pH7r",
    "status": "transcribed",
    "created_on": "2018-05-05T23:23:22.29Z",
    "callback_url": "https://www.example.com/callback",
    "duration_seconds": 356.24,
    "media_url": "https://www.rev.ai/FTC_Sample_1.mp3"
  }
}

On Failed Transcription Job

{
  "job": {
    "id": "Umx5c6F7pH7r",
    "status": "failed",
    "created_on": "2018-05-05T23:23:22.29Z",
    "callback_url": "https://www.example.com/callback",
    "failure": "download_failure",
    "failure_detail": "Failed to download media file. Please check your url and file type"
  }
}

Important notes for using webhooks:
The API will make a POST request, not a GET request, to the callback_url. The request body is the job details.
You can unsubscribe from a webhook by responding to the webhook request with a 200 response.
If a webhook invocation does not receive a 200 Rev.ai will…

Endpoints 7

Account

  • GETGet Account/accountGet the developer's account information

Jobs

  • GETGet List of Jobs/jobs?limit=0&starting_after=stringGets 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:…
  • POSTSubmit Transcription Job/jobsStarts 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…
  • GETGet Job By Id/jobs/:idReturns information about a transcription job
  • DELETEDelete Job by Id/jobs/:idDeletes 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…

Captions

  • GETGet Captions/jobs/:id/captions?speaker_channel=0Returns the caption output for a transcription job. We currently support SubRip (SRT) and Web Video Text Tracks (VTT) output. Caption output format can be…

Transcript

  • GETGet Transcript By Id/jobs/:id/transcriptReturns the transcript for a completed transcription job. Transcript can be returned as either JSON or plaintext format. Transcript output format can be…

API details

Base URL
https://api.rev.ai/speechtotext/v1
Authentication
A bearer token in the Authorization header
Operations
7 operations on 5 pathsGET 5POST 1DELETE 1
Main resources
Jobs 4Account 1Captions 1Transcript 1
Response formats
application/json application/problem+json application/vnd.rev.transcript.v1.0+json application/x-subrip
Description format
OpenAPI 3.0.1, API version v1
Listed from
APIs.guru OpenAPI Directory (CC0-1.0)
Source updated

How to test the Asynchronous Speech-To-Text API Documentation in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Asynchronous Speech-To-Text API Documentation collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Get Account” (GET /account), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Asynchronous Speech-To-Text API Documentation?

Rev.ai provides quality speech-text recognition via a RESTful API. All public methods and objects are documented here for developer reference. For a real-time… It is listed under AI & machine learning and has 7 endpoints.

Who publishes the Asynchronous Speech-To-Text API Documentation?

It is listed from Rev's public API description (an OpenAPI document), not published by Rev on Swastik Codes. Anyone who controls rev.ai can claim the profile by adding a DNS TXT record.

What is the base URL of the Asynchronous Speech-To-Text API Documentation?

Requests go to https://api.rev.ai/speechtotext/v1. Endpoint paths are added to this base URL.

How do I authenticate with the Asynchronous Speech-To-Text API Documentation?

With A bearer token in the Authorization header.

How many endpoints does the Asynchronous Speech-To-Text API Documentation have?

7 operations on 5 paths (5 GET, 1 POST, 1 DELETE). The largest groups are Jobs, Account, Captions, Transcript.

Is forking the Asynchronous Speech-To-Text API Documentation free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.