{
  "added": "2021-01-13T13:29:11.581Z",
  "info": {
    "description": "Rev.ai provides quality speech-text recognition via a RESTful API. All public methods and objects are documented here for developer reference.\nFor a real-time speech to text solution, use Rev.ai's [Streaming API](/docs/streaming).\n\n# Base Endpoint\n\nThe base url for this version of the API is\n\n> `https://api.rev.ai/speechtotext/v1`\n\nAll endpoints described in this documentation are relative to this base url.\n\n# Quick Start\n\nFollow the [getting started checklist](https://www.rev.ai/getting_started)\n\n## Get your Access Token\n\nYou 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.\n\n## Submit a File\n\nTo submit an audio file for transcription to Rev.ai:\n\n```\ncurl -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\\\"}\"\n```\n\nYou’ll receive a response like this:\n\n~~~\n{\n  \"id\": \"Umx5c6F7pH7r\",\n  \"created_on\": \"2018-09-15T05:14:38.13\",\n  \"name\": \"sample.mp3\",\n  \"metadata\": \"This is a sample submit jobs option for multipart\",\n  \"status\": \"in_progress\"\n}\n~~~\n\nThe `id` (in this case `Umx5c6F7pH7r`) will allow you to retrieve your transcript.\n\n## Get Your Transcript\n\nOnce a transcription job's `status` becomes `transcribed`, you can retrieve the transcript in JSON format by running:\n\n```\ncurl -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\"\n```\n\nAlternatively you can get the plain text version by running:\n\n```\ncurl -X GET \"https://api.rev.ai/speechtotext/v1/jobs/{id}/transcript\" -H \"Authorization: Bearer $REV_ACCESS_TOKEN\" -H \"Accept: text/plain\"\n```\n\nYou can poll for the `status` of your job by querying for the job periodically:\n\n```\ncurl -X GET https://api.rev.ai/speechtotext/v1/jobs/{id} -H \"Authorization: Bearer $REV_ACCESS_TOKEN\"\n```\n\n**Note:** Polling is NOT recommended in a production server. Rather, use [webhooks](#section/Webhooks) to asynchronously receive notifications once the transcription job completes\n\nIf you have any further questions, contact us at <support@rev.ai>\n\n# Submitting Files\n\nTwo `POST` request formats can be used to submit a file: `application/json` or `multipart/form-data`.\n\n## JSON\n\nThis is the preferred method of file submission. Uses the `media_url` property to provide a direct download URL to the Rev.ai server.\nThis 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.\n\n**Important note on presigned URLs:**\nSigned 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.\nIn the event you plan on resending the same file, make sure to generate a new presigned URL.\n\n## FormData\n\nUsed to send a local file to the Rev.ai server. This allows the customer to send the file directly from the host machine.\nCertain limits apply to this format, see the [Async API Limits section](#section/Async-API-Limits) for more detals.\n\n# Turnaround Time and Chunking\n\nOften, 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 <support@rev.ai>\n\nChunking 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.\n\n# Webhooks\n\nIf the optional `callback_url` is provided, the API will make an HTTP POST request to the `callback_url` with the\nfollowing request body when the job either completes successfully or fails.\n\n## Sample Webhook\n\n**On Successful Transcription Job**\n\n```\n{\n  \"job\": {\n    \"id\": \"Umx5c6F7pH7r\",\n    \"status\": \"transcribed\",\n    \"created_on\": \"2018-05-05T23:23:22.29Z\",\n    \"callback_url\": \"https://www.example.com/callback\",\n    \"duration_seconds\": 356.24,\n    \"media_url\": \"https://www.rev.ai/FTC_Sample_1.mp3\"\n  }\n}\n```\n\n**On Failed Transcription Job**\n\n```\n{\n  \"job\": {\n    \"id\": \"Umx5c6F7pH7r\",\n    \"status\": \"failed\",\n    \"created_on\": \"2018-05-05T23:23:22.29Z\",\n    \"callback_url\": \"https://www.example.com/callback\",\n    \"failure\": \"download_failure\",\n    \"failure_detail\": \"Failed to download media file. Please check your url and file type\"\n  }\n}\n```\n\n**Important notes for using webhooks:**\nThe API will make a POST request, not a GET request, to the `callback_url`. The request body is the job details.\nYou can unsubscribe from a webhook by responding to the webhook request with a 200 response.\nIf 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.\n\nFor initial webhook testing, you can try using a third party webhook testing tool such as [https://webhook.site/](https://webhook.site/).\n\n# Async API Limits\n\nThe following default limits apply per user, per endpoint and are configurable by Rev.ai support. If you have any further questions, contact us at <support@rev.ai>\n\n- 10,000 transcription requests submitted every 10 minutes\n- 500 transcriptions processed every 10 minutes\n- Multi-part/form-data requests to the /jobs endpoint have a concurrency limit of 10 and a file size limit of 2GB\n- POST requests to the /jobs endpoint that use the media_url property do not have a concurrency limit or file restriction. They are only limited by the first two bullet points\n\n# Error Handling\n\nThe API indicates failure with 4xx and 5xx HTTP status codes. 4xx status codes indicate an error due to the request provided (e.g., a required parameter was omitted). 5xx error indicate an error with Rev.ai's servers.\n\nWhen an 4xx error occurs during invocation of a request, the API responds with a [problem details](https://tools.ietf.org/html/rfc7807) as HTTP response payload.\n\nThe problem details information is represented as a JSON object with the following optional properties:\n\n| Property   | Description                                   |\n|------------|-----------------------------------------------|\n| type       | a URI representing the type for the error     |\n| title      | a short human readable description of type    |\n| details    | additional details of the error               |\n| status     | HTTP status code of the error                 |\n\nIn addition to the properties listed above, the problem details object may list additional properties that help to troubleshoot the problem.\n\n## Example Errors\n\n```\n// Bad Submit Job Request\n{\n  \"parameter\": {\n    \"media_url\": [\n      \"The media_url field is required\"\n    ]\n  },\n  \"type\": \"https://www.rev.ai/api/v1/errors/invalid-parameters\",\n  \"title\": \"Your request parameters didn't validate\",\n  \"status\": 400\n}\n\n// Invalid Transcript State\n{\n  \"allowed_values\": [\n    \"transcribed\"\n  ],\n  \"current_value\": \"in_progress\",\n  \"type\": \"https://rev.ai/api/v1/errors/invalid-job-state\",\n  \"title\": \"Job is in invalid state\",\n  \"detail\": \"Job is in invalid state to obtain the transcript\",\n  \"status\": 409\n}\n```\n\n## Retrying Failed Requests\n\nSome errors can be resolved simply by retrying the request. The following error codes are likely to be resolved with successive retries.\n\n| Status Code | Error |\n|---|:---|\n| 429 | Too Many Requests |\n| 502 | Bad Gateway |\n| 503 | Service Unavailable |\n| 504 | Gateway Timeout |\n\nNote: With the exception of the 429 status code, it is recommended that the maximum number of retries be limited to 5 attempts per request. The number of retries can be higher\nfor 429 errors but if you notice consistent throttling please contact us at <support@rev.ai>.\n",
    "title": "Asynchronous Speech-To-Text API Documentation",
    "version": "v1",
    "x-apisguru-categories": [
      "text"
    ],
    "x-logo": {
      "url": "https://api.apis.guru/v2/cache/logo/https_rev.ai_content_curve_img_revai_favicon.png"
    },
    "x-origin": [
      {
        "format": "openapi",
        "url": "http://api.rev.ai/openapi/v1/documentation.yaml",
        "version": "3.0"
      }
    ],
    "x-providerName": "rev.ai"
  },
  "updated": "2021-08-02T08:20:08.766Z",
  "swaggerUrl": "https://api.apis.guru/v2/specs/rev.ai/v1/openapi.json",
  "swaggerYamlUrl": "https://api.apis.guru/v2/specs/rev.ai/v1/openapi.yaml",
  "openapiVer": "3.0.1",
  "link": "https://api.apis.guru/v2/specs/rev.ai/v1.json"
}