canonical: https://jentic.com/apis/rev.ai/rev

# Rev Asynchronous Speech-To-Text API Documentation

The Rev.ai Asynchronous Speech-To-Text API transcribes recorded audio and video files into text. You submit a job with a public media_url or a multipart file upload, Rev.ai processes it in the background and can call your callback_url when it finishes, and you then fetch the transcript as JSON or plain text, or captions as SRT or VTT. Job options cover language, speaker diarization, punctuation, profanity filtering, disfluency removal, custom vocabularies, and automatic deletion after a set number of seconds.

## For AI agents

Submit recorded audio or video for asynchronous transcription, poll or receive a callback when it is done, and fetch the transcript as JSON or text, or captions as SRT or VTT.

## Scope

Does not handle live streaming transcription, text-to-speech, translation, or human transcription orders. Use for asynchronous transcription of recorded audio and video only.

## Capabilities

- Start a transcription job from a public media_url or a multipart media upload of under 2GB with POST /jobs
- Get notified at a callback_url when a job finishes instead of polling
- Fetch a finished transcript as speaker monologues in JSON or as plain text from `/jobs/{id}/transcript`
- Download captions in SubRip (SRT) or WebVTT format from `/jobs/{id}/captions`
- Tune a job with language, skip_diarization, skip_punctuation, filter_profanity, remove_disfluencies, and custom_vocabularies
- Check remaining balance_seconds on the account with GET /account
- Permanently delete a completed job and its media and transcript with DELETE `/jobs/{id}`, or set delete_after_seconds up front

## Use cases

### Agent-run meeting transcription through Jentic

An assistant agent connected through Jentic searches by intent for transcribing a recording, gets SubmitTranscriptionJob with its schema, and submits the meeting's media_url with a callback_url. When the job status becomes transcribed, the agent fetches the JSON transcript with its speaker monologues and writes up a summary with who said what.

Example prompt: POST /jobs with media_url 'https://example.com/meeting.mp3', language 'en', and callback_url 'https://example.com/hooks/rev', then GET `/jobs/{id}/transcript` once the job status is transcribed

### Captions for recorded video

A video publishing pipeline submits each upload to Rev.ai, then requests captions from `/jobs/{id}/captions` with an Accept header of text/vtt for web players or application/x-subrip for SRT. Captions default to SRT, and speaker_channel lets you request captions for one channel of a multichannel recording.

Example prompt: POST /jobs with media_url 'https://example.com/webinar.mp4', then GET `/jobs/{id}/captions` with Accept 'text/vtt' once the job is transcribed

### Domain vocabulary and privacy controls

For medical, legal, or product recordings full of unusual terms, a job can pass custom_vocabularies or a custom_vocabulary_id to improve recognition of those words. Setting delete_after_seconds, or calling DELETE `/jobs/{id}` after download, removes the media and transcript from Rev.ai so sensitive recordings are not retained.

Example prompt: POST /jobs with media_url 'https://example.com/consult.wav', custom_vocabularies listing the product names, and delete_after_seconds 86400

### Job tracking and failure handling

GET /jobs lists jobs from the last 30 days in reverse chronological order, paged with limit and starting_after. For any job whose status is failed, the failure field gives a reason code such as invalid_media, duration_exceeded, or insufficient_balance, with failure_detail explaining it, so an agent can resubmit or alert you.

Example prompt: GET /jobs with limit 50, then for each job whose status is failed report its failure and failure_detail values

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/jobs` | Submit a transcription job |
| GET | `/jobs/{id}` | Get job status and details |
| GET | `/jobs/{id}/transcript` | Get the transcript |
| GET | `/jobs/{id}/captions` | Get SRT or VTT captions |
| GET | `/jobs` | List recent jobs |
| DELETE | `/jobs/{id}` | Delete a job and its data |
| GET | `/account` | Get account balance |

## Key resources

- **Jobs** — Asynchronous transcription jobs with status, options, duration, and failure reason
- **Transcripts** — Speaker monologues in JSON, or plain text
- **Captions** — SRT or VTT caption files for a finished job
- **Account** — Account email and remaining balance_seconds

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 74 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 63 / 100
  - Developer Experience & Jentic Compatibility: 69 / 100
  - AI-Readiness & Agent Experience: 73 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 100 / 100
- **View full report:** https://jentic.com/apis/rev.ai/rev/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Rev.ai by hand means handling its bearer access token, choosing between JSON and multipart job submission, setting the right Accept header for transcript and caption formats, and running callbacks or polling. Through Jentic you install once, import the Rev.ai API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Rev.ai puts the job id in the URL path (`/jobs/{id}/...`), so a rule can limit your agent to reading one job's transcript and captions. You choose the operations it may call, so destructive ones like DeleteJobById are not included unless you add them.
- **Credential handling:** Your Rev.ai access token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'transcribe an audio file' or 'get captions for a video', and Jentic returns the matching Rev.ai operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **AssemblyAI API** — Speech-to-text with audio intelligence features
- **Deepgram API** — Speech-to-text for recorded and live audio
- **Gladia API** — Multilingual audio transcription
- **OpenAI API** — Language models for summarising and extracting from text

## FAQ

### What authentication does the Rev.ai Speech-To-Text API use?

Per its OpenAPI spec, requests carry an access token as a bearer token in the Authorization header. You generate the token once on your Rev.ai settings page, and the spec notes it does not expire. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at call time.

### Which languages can the Rev.ai Speech-To-Text API transcribe?

The language option on POST /jobs accepts 31 language codes in the spec, such as en, es, fr, de, ja, cmn, and hi. The spec notes that media longer than 17 hours is not supported for English and longer than 12 hours for other languages, and non-English jobs can take up to 6 hours.

### What are the rate limits for the Rev.ai Speech-To-Text API?

The OpenAPI spec does not specify rate limits. Check https://docs.rev.ai for current limits. The spec does cap direct uploads at under 2GB, so larger files should be submitted by media_url.

### Is there a Rev.ai MCP server?

You don't need an MCP server to give your agent the Rev.ai Speech-To-Text API. Jentic connects it directly from the API Directory: import it, store your access token once, and your agent calls it. Operations are found by intent when needed, so no extra tool definitions sit in your agent's context.

### How do I transcribe an audio file through Jentic?

Install Jentic One, add the Rev.ai Speech-To-Text API from the directory, and store your access token. Your agent searches for 'transcribe an audio file', gets POST /jobs with its schema, submits the media_url, then calls GET `/jobs/{id}/transcript` once the status is transcribed. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Rev.ai Speech-To-Text API?

Yes. Write a rule that allows only POST /jobs, GET `/jobs/{id}`, and GET `/jobs/{id}/transcript`, so the agent can submit recordings, check status, and read transcripts but cannot delete jobs or list your other jobs, and every call it makes is logged.
