Libraries & SDKs

The official SDKs wrap every Sarvam AI API — Speech-to-Text, Text-to-Speech, Instant Voice Cloning, Translation, Chat Completion, and Document AI — behind a typed, ergonomic client. They handle auth, serialization, multipart uploads, and error mapping so you don’t have to hand-roll HTTP calls.

Initialize the client

Pass your API key directly, or let the SDK read it from the SARVAM_API_KEY environment variable.

from sarvamai import SarvamAI
client = SarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")
response = client.text.translate(
    input="Hello, how are you?",
    source_language_code="auto",
    target_language_code="hi-IN",
)
print(response)

Async usage

Both SDKs support fully asynchronous calls. Use them when you need concurrency (e.g. fanning out many requests, or inside an async web server or voice agent).

import asyncio
from sarvamai import AsyncSarvamAI
client = AsyncSarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")
async def main():
    # Run several translations concurrently
    inputs = ["Good morning", "How are you?", "Thank you"]
    results = await asyncio.gather(*[
        client.text.translate(
            input=text,
            source_language_code="en-IN",
            target_language_code="hi-IN",
        )
        for text in inputs
    ])
    for r in results:
        print(r)
asyncio.run(main())

Timeouts and retries

Configure timeouts and automatic retries either globally (on the client) or per request. Per-request options override the client defaults.

from sarvamai import SarvamAI
# Client-level: applies to every request
client = SarvamAI(
    api_subscription_key="YOUR_SARVAM_API_KEY",
    timeout=30.0,  # seconds
)
# Per-request: override timeout and set automatic retries
response = client.text.translate(
    input="Hello, how are you?",
    source_language_code="auto",
    target_language_code="hi-IN",
    request_options={
        "timeout_in_seconds": 60,
        "max_retries": 3,
    },
)

Retries use exponential backoff and apply to transient failures (HTTP 429, 5xx, and connection errors). For a full retry/backoff helper and idempotency guidance, see Errors & Troubleshooting.

Handling errors

The SDKs raise typed exceptions mapped to HTTP status codes, so you can catch exactly the failure you care about. Catch the base class to handle everything.

from sarvamai import SarvamAI, TooManyRequestsError
from sarvamai.core.api_error import ApiError
client = SarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")
try:
    response = client.text.translate(
        input="Hello, how are you?",
        source_language_code="auto",
        target_language_code="hi-IN",
    )
except TooManyRequestsError:
    print("Rate limited, back off and retry")
except ApiError as e:
    # Base class for every API error
    print(f"API error {e.status_code}: {e.body}")

Exception reference

¹ Auth failures return HTTP 403 (invalid_api_key_error), not 401. See the auth status-code note.

² Most endpoints, including Chat, Speech-to-Text, Text-to-Speech and Translate, have no dedicated 402 exception, so an empty credit balance raises the base error with status_code == 402 in Python or statusCode === 402 in JavaScript (insufficient_quota_error). Document Intelligence, Document Translation and Voice Cloning raise PaymentRequiredError. Catch the base error, check the status code, and do not retry. See Errors & Troubleshooting.

Streaming support

Several APIs stream results instead of returning a single response. Here’s what each SDK supports:

• HTTP streaming returns an iterable/BinaryResponse of raw audio bytes. See the TTS HTTP Streaming guide and Instant Voice Cloning HTTP streaming.
• WebSocket streaming uses the async clients (AsyncSarvamAI / SarvamAIClient) with an event-driven connection. See the TTS WebSocket, Instant Voice Cloning WebSocket, and STT WebSocket guides.

Document AI (file uploads)

Document AI is the one group that takes file uploads rather than JSON, so its call shape differs from the rest of the SDK. Both clients expose it as a doc_ai / docAi group, and a job is created in a single parse() or extract() call.

import os, time
from sarvamai import SarvamAI
client = SarvamAI(api_subscription_key=os.environ["SARVAM_API_KEY"])
# `file` takes a list of (filename, fileobj, content_type) tuples
with open("document.pdf", "rb") as f:
    job = client.doc_ai.parse(
        file=[("document.pdf", f, "application/pdf")],
        language="hi-IN",
        output_format="md",   # "html" (default) or "md"
    )
TERMINAL = {"completed", "partially_completed", "failed", "rejected"}
while True:
    st = client.doc_ai.get_status(job_id=job.job_id)
    if st.status.lower() in TERMINAL:
        break
    time.sleep(5)
dl = client.doc_ai.get_download_url(job_id=job.job_id)
print("download:", dl.method, dl.url)

See the Document AI overview for the four operations, How to extract for schema rules, and Jobs & Errors for the full job lifecycle. The older document_intelligence group (create_job() / upload_file() / start() / wait_until_complete() / download_output()) is still present for existing integrations, but new work should use doc_ai.

Versioning

The SDKs follow semantic versioning. Pin a version in production and review the API changelog before upgrading across a major version. Always develop against the latest release:

pip install --upgrade sarvamai

Resources