Rev AI Python SDK

Common errors

• 401 Authorization Denied

  cause The provided Rev AI Access Token is invalid, expired, or missing in the request.
  fix Ensure your `REVAI_ACCESS_TOKEN` environment variable or direct client initialization uses a valid, current access token from your Rev AI account.

• Error: Unsupported Language - The requested language is not supported by the API.

  cause Attempting to transcribe audio in a language that the Rev AI API does not currently support for the specified transcriber or API endpoint.
  fix Consult the Rev AI API documentation for a list of supported languages and their availability for asynchronous, streaming, or specific transcriber models. Ensure the `language` parameter (if used) matches a supported code.

• Callback Failure: Callback URL unreachable or server did not respond.

  cause The webhook URL provided in `notification_config` (or deprecated `callback_url`) is inaccessible, misconfigured, or your server failed to respond correctly to Rev AI's callback.
  fix Verify the callback URL is publicly accessible, correctly configured, and that your server is running and can process incoming POST requests from Rev AI. Test the URL independently.

• 400 Invalid Request / Malformed input

  cause One or more parameters submitted with your transcription job (e.g., file path, custom vocabulary, API options) are invalid, missing, or malformed according to the API specification.
  fix Carefully review the Rev AI API documentation for the specific endpoint and ensure all required parameters are present and correctly formatted, and that values are within acceptable ranges.

Warnings

• breaking The `media_url` and `callback_url` parameters were deprecated in SDK version 2.16.0 in favor of `source_config` and `notification_config`. While the old parameters are still supported in the API, future SDK versions may remove support.
  Fix: Migrate to `source_config` for specifying audio URLs and `notification_config` for webhook callbacks. These new parameters offer enhanced security and allow for authentication headers.
• gotcha Rev AI APIs have rate limits (e.g., 10,000 requests/10 minutes, 500 processed/10 minutes) and file size limits (2GB for multipart/form-data, 5TB via `source_config` with URL). Exceeding these limits can lead to queued jobs or API errors.
  Fix: Implement robust error handling and retry mechanisms with exponential backoff. For large-scale usage, consider optimizing job submission patterns or contacting Rev AI support to adjust limits.
• gotcha Different base URLs are used for non-US deployments. Using the incorrect base URL for your selected deployment will result in connection errors or incorrect data routing.
  Fix: When initializing `RevAiAPIClient`, pass the correct `url` parameter using `RevAiApiDeploymentConfigMap` and `RevAiApiDeployment` for your specific region (e.g., EU).
• gotcha Polling for job status, as shown in simple quickstarts, is inefficient for high-volume or long-running jobs. It can lead to unnecessary API calls and potential rate limiting.
  Fix: For production applications, use webhooks (`notification_config`) to receive asynchronous notifications when a job's status changes.

Install

• pip install --upgrade rev-ai Install latest version

Imports

• RevAiAPIClient
  wrong:

  from rev_ai.apiclient import RevAiAPIClient

  correct:

  from rev_ai import apiclient

  RevAiAPIClient is exposed directly under `rev_ai.apiclient`, so `from rev_ai import apiclient` and then `apiclient.RevAiAPIClient` is the standard pattern.
• RevAiStreamingClient

  from rev_ai.streamingclient import RevAiStreamingClient

• MediaConfig

  from rev_ai.models import MediaConfig

• RevAiApiDeployment

  from rev_ai import apiclient, RevAiApiDeploymentConfigMap, RevAiApiDeployment

  Used for configuring specific API deployment regions, e.g., for EU.

Quickstart

This quickstart demonstrates how to initialize the Rev AI client, submit a local audio file for transcription, poll for job completion, retrieve the transcript as text, and finally delete the job. Remember to replace the placeholder `AUDIO_FILE_PATH` and set your `REVAI_ACCESS_TOKEN` environment variable.

import os
import time
from rev_ai import apiclient

REVAI_ACCESS_TOKEN = os.environ.get('REVAI_ACCESS_TOKEN', 'YOUR_REVAI_ACCESS_TOKEN')
AUDIO_FILE_PATH = 'path/to/your/audio.mp3'  # Replace with your audio file path

if not REVAI_ACCESS_TOKEN or REVAI_ACCESS_TOKEN == 'YOUR_REVAI_ACCESS_TOKEN':
    print("Please set the REVAI_ACCESS_TOKEN environment variable or replace 'YOUR_REVAI_ACCESS_TOKEN' with your actual token.")
    exit(1)

if not os.path.exists(AUDIO_FILE_PATH):
    print(f"Audio file not found: {AUDIO_FILE_PATH}")
    print("Please replace 'path/to/your/audio.mp3' with a valid audio file path.")
    exit(1)

# Create your client
client = apiclient.RevAiAPIClient(REVAI_ACCESS_TOKEN)

print(f"Submitting job for: {AUDIO_FILE_PATH}")
# Submit a local file for transcription
job = client.submit_job_local_file(AUDIO_FILE_PATH)

job_id = job.id
print(f"Job submitted with ID: {job_id}")

# Polling for job completion (simple example, consider webhooks for production)
while True:
    job_details = client.get_job_details(job_id)
    if job_details.status == 'transcribed':
        print("Job transcribed successfully!")
        break
    elif job_details.status == 'failed':
        print(f"Job failed: {job_details.failure_detail}")
        exit(1)
    else:
        print(f"Job status: {job_details.status}... waiting")
        time.sleep(5) # Wait 5 seconds before checking again

# Retrieve transcript as text
transcript_text = client.get_transcript_text(job_id)
print("\n--- Transcript (Text) ---")
print(transcript_text[:500]) # Print first 500 characters
print("...")

# You can also retrieve as JSON or a Python object
# transcript_json = client.get_transcript_json(job_id)
# transcript_object = client.get_transcript_object(job_id)

# Delete the job (optional, but good practice for cost/data management)
client.delete_job(job_id)
print(f"Job {job_id} deleted.")