Batch Speech-to-Text (STT) API Tutorial Using Saarika Model

Overview

This guide demonstrates how to use Sarvam AI’s Batch Speech-to-Text (STT) API for transcribing audio files at scale. You’ll learn both synchronous and asynchronous usage patterns, understand key parameters, and see how to upload files, poll for job completion, and download results.

1. Installation

Install the Sarvam AI Python SDK:

1
!pip install -U sarvamai

2. API Key Setup

1. Get your API key: Sign up at the Sarvam AI Dashboard to obtain your API key.
2. Set your API key: Replace "YOUR_API_KEY_HERE" in the code below with your actual key.

1
API_KEY = "YOUR_API_KEY_HERE"

3. STT Parameters

4. Synchronous STT Batch Example

1
from pathlib import Path
2
from sarvamai import SarvamAI
3
4
API_KEY = "YOUR_API_KEY_HERE"
5
audio_files = ["/path/to/your/audio.mp3"]  # Update with your file path
6
output_dir = Path("/output")
7
output_dir.mkdir(exist_ok=True)
8
9
def run_stt_sync():
10
    client = SarvamAI(api_subscription_key=API_KEY)
11
    job = client.speech_to_text_job.create_job(
12
        model="saarika:v2.5",
13
        with_diarization=True,
14
        with_timestamps=True,
15
        language_code="en-IN",
16
        num_speakers=2,
17
    )
18
    print(f"Job created: {job._job_id}")
19
    job.upload_files(file_paths=audio_files, timeout=120.0)
20
    job.start()
21
    print("Transcription started...")
22
    job.wait_until_complete(poll_interval=5, timeout=60)
23
    
24
    if job.is_failed():
25
        raise RuntimeError("Transcription failed")
26
    
27
    job.download_outputs(output_dir=str(output_dir))
28
    print(f"Transcription completed. Output saved to: {output_dir}")
29
30
run_stt_sync()

5. Asynchronous STT Batch Example

1
import asyncio
2
from pathlib import Path
3
from sarvamai import AsyncSarvamAI
4
5
API_KEY = "YOUR_API_KEY_HERE"
6
audio_files = ["/path/to/your/audio.mp3"]  # Update with your file path
7
output_dir = Path("/output")
8
output_dir.mkdir(exist_ok=True)
9
10
async def run_stt_async_job():
11
    client = AsyncSarvamAI(api_subscription_key=API_KEY)
12
    job = await client.speech_to_text_job.create_job(
13
        model="saarika:v2.5",
14
        with_diarization=True,
15
        with_timestamps=True,
16
        language_code="en-IN",
17
        num_speakers=2,
18
    )
19
    print(f"Job created: {job._job_id}")
20
    await job.upload_files(file_paths=audio_files, timeout=120.0)
21
    await job.start()
22
    print("Transcription started...")
23
    await job.wait_until_complete(poll_interval=5, timeout=60)
24
    
25
    if job.is_failed():
26
        raise RuntimeError("Transcription failed")
27
    
28
    await job.download_outputs(output_dir=str(output_dir))
29
    print(f"Transcription completed. Output saved to: {output_dir}")
30
31
# For Jupyter environments:
32
import nest_asyncio
33
nest_asyncio.apply()
34
await run_stt_async_job()

6. Tips & Best Practices

• Audio Quality: Use clear audio for best results.
• Diarization: Set with_diarization=True and specify num_speakers for multi-speaker audio.
• Polling: Adjust poll_interval and timeout based on expected job duration and file size.
• Output: Results are saved in the specified output_dir.
• API Key Security: Keep your API key confidential.

7. Error Handling

You may encounter these errors while using the API:

• 403 Forbidden (invalid_api_key_error)

  • Cause: Invalid API key.
  • Solution: Use a valid API key from the Sarvam AI Dashboard.

• 429 Too Many Requests (insufficient_quota_error)

  • Cause: Exceeded API quota.
  • Solution: Check your usage, upgrade if needed, or implement exponential backoff when retrying.

• 500 Internal Server Error (internal_server_error)

  • Cause: Issue on our servers.
  • Solution: Try again later. If persistent, contact support.

• 400 Bad Request (invalid_request_error)

  • Cause: Incorrect request formatting.
  • Solution: Verify your request structure, and parameters.

• 422 Unprocessable Entity Request (unprocessable_entity_error)

  • Cause: Unable to detect the language of the input text.
  • Solution: Explicitly pass the source_language_code parameter with a supported language.

8. Additional Resources

For more details, refer to the our official documentation and we are always there to support and help you on our Discord Server:

• Documentation: docs.sarvam.ai
• Community: Join the Discord Community

9. Final Notes

• Keep your API key secure.
• Use clear audio for best results.
• Check audio quality and supported formats.
• Increase timeout for large files or slow networks.

Keep Building! 🚀