About
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](/docs/streaming). # 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](https://www.rev.ai/getting_started) ## Get your Access Token You can generate your [access token](#section/Authentication/Access-Token) on the [settings page](https://www.rev.ai/access_token) 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](#section/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](#section/Async-API-Limits) 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 retry the `callback_url` every 30 minutes until either 24 hours have passed or we receive a 200 response. For ini