Document Translation API Overview

The Document Translation API takes a source document and returns it translated into one or more Indian languages, in its original file format. The layout, formatting, and structure of the source file are preserved.

What you get from one job

A single job translates into up to 12 target languages (out of 23 total supported) from one uploaded document. You upload once, and each target language is translated independently and exported separately.

How it works

Document translation is asynchronous by design: you create a job, upload the file, start the pipeline, poll it, and then export each language’s result, rather than getting a translated file back from a single request. Every integration follows the same five steps:

Quickstart

Install the SDK (pip install sarvamai or npm install sarvamai), set SARVAM_API_KEY, and point document at a local PDF or Office file. The client uses https://api.sarvam.ai by default, so your API key is the only configuration it needs.

1
import os
2
from pathlib import Path
3
4
import httpx
5
from sarvamai import SarvamAI
6
7
client = SarvamAI(api_subscription_key=os.environ["SARVAM_API_KEY"])
8
document = Path("chapter1.pdf")
9
10
# 1. Create job (auto_process=True is the default)
11
job = client.document_translation.create(
12
    job_name="chapter1",
13
    source_language_code="en-IN",
14
    target_language_codes=["hi-IN", "ta-IN"],
15
    original_filename=document.name,
16
    auto_process=True,
17
    model_type="plus",
18
)
19
20
# 2. Upload to the signed URL (required — not handled by the SDK)
21
with document.open("rb") as f:
22
    httpx.put(
23
        job.upload_url,
24
        content=f.read(),
25
        headers={
26
            "Content-Type": "application/pdf",
27
            "x-ms-blob-type": "BlockBlob",
28
        },
29
        timeout=120.0,
30
    )
31
32
# 3. Start the pipeline (required even when auto_process=True)
33
client.document_translation.start(job_id=job.job_id)
34
35
# 4–5. Poll translation, then export — see Poll and Export guide
36
print(job.job_id)

That job is now running. See Poll and Export for the polling loop and per-language download flow.

Page-granular vs document-granular responses

The response format depends on the uploaded file type:

• PDFs are tracked per page.
• Word, spreadsheets, and presentations are tracked per text segment (roughly a paragraph).

Both response formats share the same base fields. Only the progress-related fields differ.

Response shapes at a glance

Shared fields (both response types)

job_id job_state job_name source_language_code progress translations[] created_at updated_at

Job states

Terminal states are Completed, PartiallyCompleted, and Failed.

Each language in translations[] has its own state (Pending, Running, Completed, Failed), independent of the others. A language is exportable as soon as its own entry reads Completed, even while other languages in the same job are still Running. Treat PartiallyCompleted as a terminal state alongside Completed, and check each language’s own state before deciding what to export.

Request parameters

Required:

Optional:

Supported file formats

Supported languages

23 languages: English plus 22 Indic languages.

Response examples

POST /translate/document/jobs returns 201 Created:

1
{
2
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
3
  "upload_url": "https://api.sarvam.ai/translate/document/uploads/550e8400-e29b-41d4-a716-446655440000?sig=...",
4
  "expires_in_hours": 24,
5
  "source_language_code": "en-IN",
6
  "target_language_codes": ["hi-IN", "ta-IN"]
7
}

GET /translate/document/jobs/{job_id}/live-status returns:

1
{
2
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
3
  "job_name": "chapter1",
4
  "job_state": "Running",
5
  "source_language_code": "en-IN",
6
  "progress": 55,
7
  "page_metrics": {
8
    "total_pages": 42,
9
    "pages_processed": 23,
10
    "pages_succeeded": 23,
11
    "pages_failed": 0
12
  },
13
  "translations": [
14
    {
15
      "target_language_code": "hi-IN",
16
      "state": "Running",
17
      "pages_completed": 12,
18
      "pages_failed": 0
19
    },
20
    {
21
      "target_language_code": "ta-IN",
22
      "state": "Pending",
23
      "pages_completed": 0,
24
      "pages_failed": 0
25
    }
26
  ],
27
  "created_at": "2026-08-04T10:00:00Z",
28
  "updated_at": "2026-08-04T10:05:00Z"
29
}

GET /translate/document/jobs/{job_id}/export/status returns, once the export is Completed:

1
{
2
  "export_id": "exp_1a2b3c4d",
3
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
4
  "target_language_code": "hi-IN",
5
  "format": "pdf",
6
  "export_state": "Completed",
7
  "download_url": "https://api.sarvam.ai/translate/document/exports/550e8400-e29b-41d4-a716-446655440000/hi-IN?sig=...",
8
  "filename": "chapter1_hi-IN.pdf",
9
  "expires_in_hours": 24,
10
  "file_size": 1048576,
11
  "created_at": "2026-08-04T10:10:00Z",
12
  "completed_at": "2026-08-04T10:12:30Z"
13
}

Errors

Best Practices

Limits

Next Steps