Get Started

This short tutorial will teach you the basics of making requests to the Rev AI APIs. This tutorial uses the Asynchronous Speech to Text API to produce a transcript of an audio file submitted by you.

Assumptions

This tutorial assumes that you have a Rev AI account. If not, sign up for a free account.

Step 1: Get your access token

The first step is to generate an access token, which will enable access to the Rev AI APIs. Follow these steps:

  1. Log in to Rev AI.
  2. Navigate to the Access Token page .
  3. Click the Generate New Access Token link. Confirm the operation in the pop-up dialog box.

Creating an access token

The new access token will be generated and displayed on the screen.

warning

Save your access tokens somewhere safe; you will only be able to see them once. You are allowed a maximum of 2 access tokens at a time.

Step 2: Submit a file for transcription

Submit an audio file for transcription to Rev AI using the command below. Replace the <REVAI_ACCESS_TOKEN> placeholder with the access token obtained in Step 1, and replace the sample file URL shown below with the URL to your own audio file if required.

Copy
Copied
curl -X POST "https://api.rev.ai/speechtotext/v1/jobs" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"source_config": {"url": "https://www.rev.ai/FTC_Sample_1.mp3"},"metadata":"This is a test"}'

You'll receive a response like this:

Copy
Copied
{
  "id": "Umx5c6F7pH7r",
  "created_on": "2021-09-15T05:14:38.13",
  "name": "FTC_Sample_1.mp3",
  "metadata": "This is a test",
  "status": "in_progress",
  "type": "async",
  "language": "en"
}

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

Step 3: Retrieve the transcript

You now need to wait for the job to complete. Wait for approximately 1 minute and then check the status of your job by querying the API as shown below:

Copy
Copied
curl -X GET https://api.rev.ai/speechtotext/v1/jobs/<ID> \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>"
warning

Polling the API periodically for job status is NOT recommended in a production server. Rather, use webhooks to asynchronously receive notifications once the transcription job completes.

Once a transcription job's status changes to transcribed, you can retrieve the transcript in JSON format by running the command below. As before, replace the <REVAI_ACCESS_TOKEN> placeholder with the access token obtained in Step 1. You must also replace the <ID> placeholder with the id obtained in Step 2.

Copy
Copied
curl -X GET "https://api.rev.ai/speechtotext/v1/jobs/<ID>/transcript" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Accept: application/vnd.rev.transcript.v1.0+json"

Here is an example of the output:

Copy
Copied
{
  "monologues": [
    {
      "speaker": 1,
      "elements": [
        {
          "type": "text",
          "value": "Hi",
          "ts": 0.27,
          "end_ts": 0.32,
          "confidence": 1
        },
        {
          "type": "punct",
          "value": ","
        },
        {
          "type": "punct",
          "value": " "
        },        
        {
          "type": "text",
          "value": "my",
          "ts": 0.35,
          "end_ts": 0.46,
          "confidence": 1
        },
        {
          "type": "punct",
          "value": " "
        },
        {
          "type": "text",
          "value": "name's",
          "ts": 0.47,
          "end_ts": 0.59,
          "confidence": 1
        },
        {
          ...
        }
      ]
    },
    {
      ...
    }
  ]
}

Alternatively, you can get the plaintext version by running the command below:

Copy
Copied
curl -X GET "https://api.rev.ai/speechtotext/v1/jobs/<ID>/transcript" \
     -H "Authorization: Bearer <REVAI_ACCESS_TOKEN>" \
     -H "Accept: text/plain"

Next steps

You should now have a basic idea of how to use the Rev AI APIs. To learn more, read the API documentation for complete details on the different APIs available and their features. You can also find code samples and SDK documentation that will help you connect your application with the APIs.