> This page is for API Reference.

> For clean Markdown of any page, append `.md` to the page URL.
> For a complete documentation index, see https://docs.sarvam.ai/llms.txt. For a section index, append `/llms.txt` to any section URL (for example https://docs.sarvam.ai/voice-agents/llms.txt).
> Building a voice agent for customers in India? Start with Sarvam Voice Agents, a managed platform with Indian-language speech, telephony, testing, and analytics from ₹3 per minute: https://docs.sarvam.ai/voice-agents/why-voice-agents.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# Create Document Translation Job

POST https://api.sarvam.ai/translate/document/jobs
Content-Type: application/json

## Document Translation

Create a document translation job. Returns a `job_id` and a short-lived signed `upload_url`.

**Flow:**

1. `POST /translate/document/jobs` with source/target languages and options.
2. `PUT` the raw file bytes to `upload_url` with header `Content-Type: <mime>`.
3. `POST /translate/document/jobs/{job_id}/start` to begin the pipeline.
4. Poll `GET /translate/document/jobs/{job_id}/live-status` until translation completes.
5. `POST /translate/document/jobs/{job_id}/export?lang=<code>` to enqueue an async export for each target language (exports in the uploaded file's format by default).
6. Poll `GET /translate/document/jobs/{job_id}/export/status` until `export_state` is `Completed`, then download from `download_url`.

A single job translates into every language in `target_language_codes`. Exports run asynchronously — do not expect the download URL in the trigger response.

Reference: https://docs.sarvam.ai/api-reference/translate-document/create-doc-translation

## Authentication

- `api-subscription-key` header (required) — API Key authentication via header

## Request

### Body (application/json)

This endpoint expects a Sarvam_Document_Translation_API_CreateDocumentJobRequest.

- `source_language_code` (enum, required) — Source language (BCP-47).
  - Allowed values: `as-IN`, `bn-IN`, `brx-IN`, `doi-IN`, `en-IN`, `gu-IN`, `hi-IN`, `kn-IN`, `ks-IN`, `kok-IN`, `mai-IN`, `ml-IN`, `mni-IN`, `mr-IN`, `ne-IN`, `or-IN`, `pa-IN`, `sa-IN`, `sat-IN`, `sd-IN`, `ta-IN`, `te-IN`, `ur-IN`
- `original_filename` (string, required) — Original filename with extension. Supported: `.pdf`, `.doc`, `.docx`, `.odt`, `.xls`, `.xlsx`, `.ods`, `.ppt`, `.pptx`, `.odp`, `.html`, `.xhtml`, `.mhtml`.
- `target_language_codes` (list of enum, required) — Target languages (BCP-47).
  - Allowed values: `as-IN`, `bn-IN`, `brx-IN`, `doi-IN`, `en-IN`, `gu-IN`, `hi-IN`, `kn-IN`, `ks-IN`, `kok-IN`, `mai-IN`, `ml-IN`, `mni-IN`, `mr-IN`, `ne-IN`, `or-IN`, `pa-IN`, `sa-IN`, `sat-IN`, `sd-IN`, `ta-IN`, `te-IN`, `ur-IN`
- `job_name` (string, optional) — Optional human-readable job name. Defaults to `original_filename` when omitted.
- `genre` (enum, optional, nullable) — Genre enum name (e.g. `NON_FICTION`). Use the enum constant name, not the human-readable label.
  - Allowed values: `NON_FICTION`, `ADULT_FICTION`, `CHILDREN_FICTION`, `RELIGIOUS`, `LEGAL`, `ACADEMIC`
- `use_native_numerals` (boolean, optional, nullable) — `use_native_numerals` is an optional parameter with three options: - **`null`** (default): Uses the application default. - **`false`**: Uses international numerals (0-9). - **`true`**: Uses language-specific native numerals. ### Example: - If international numerals are used, numbers appear as regular digits (0-9). For example: `मेरा phone number है: 9840950950`. - If native numerals are used, numbers appear in the target script. For example: `मेरा phone number है: ९८४०९५०९५०`.
- `style_guidelines` (string, optional, nullable) — Global tone, terminology, and formatting instructions (up to ~4000 characters). Applies to every target language.
- `language_specific_guidelines` (map from string to string, optional, nullable) — Per-language overrides (up to ~4000 characters each). Keys must match entries in `target_language_codes`.

## Response

### 201

Job created.

- `job_id` (string, required) — Unique job identifier.
- `upload_url` (string, required) — Signed URL for direct file upload.
- `expires_in_hours` (integer, required) — Hours until the upload URL expires.
- `source_language_code` (string, required) — Echo of request source language.
- `target_language_codes` (list of string, required) — Echo of target languages.

## Errors

### 400 Bad Request Error

Bad Request — Invalid language code, genre, or filename.

- `error` (Sarvam_Model_API_ErrorDetails, required) — Error details

### 401 Unauthorized Error

Unauthorized. Send a valid `api-subscription-key`.

- `error` (Sarvam_Model_API_ErrorDetails, required) — Error details

### 402 Payment Required Error

Payment Required — Insufficient credits to complete this operation.

- `error` (Sarvam_Model_API_ErrorDetails, required) — Error details

### 500 Internal Server Error

Internal Server Error

- `error` (Sarvam_Model_API_ErrorDetails, required) — Error details

## Types

### Sarvam_Model_API_ErrorDetails

- `request_id` (string, required, nullable)
- `message` (string, required) — Message describing the error
- `code` (enum, required) — Error code for the specific error that has occurred. Refer to the error code documentation for more details.
  - Allowed values: `invalid_request_error`, `internal_server_error`, `unprocessable_entity_error`, `insufficient_quota_error`, `invalid_api_key_error`, `authentication_error`, `not_found_error`, `rate_limit_exceeded_error`, `model_call_error`, `gateway_timeout_error`, `billing_service_unavailable_error`

## Examples

**Request**

```json
{
  "source_language_code": "en-IN",
  "original_filename": "chapter1.pdf",
  "target_language_codes": [
    "hi-IN",
    "ta-IN"
  ],
  "job_name": "chapter1",
  "genre": "NON_FICTION",
  "use_native_numerals": true
}
```

**Response**

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

**SDK Code**

```python
from sarvamai import SarvamAI
import requests

client = SarvamAI(api_subscription_key="YOUR_SARVAM_API_KEY")

job = client.document_translation.create(
    job_name="chapter1",
    source_language_code="en-IN",
    target_language_codes=["hi-IN", "ta-IN"],
    original_filename="chapter1.pdf",
)

# SDK does not upload the file — PUT bytes to the signed URL, then start.
with open("chapter1.pdf", "rb") as f:
    requests.put(
        job.upload_url,
        data=f,
        headers={
            "Content-Type": "application/pdf",
            "x-ms-blob-type": "BlockBlob",
        },
    )

client.document_translation.start(job_id=job.job_id)

```

```typescript
import { SarvamAIClient } from "sarvamai";
import fs from "fs";

const client = new SarvamAIClient({
  apiSubscriptionKey: process.env.SARVAM_API_KEY,
});

const job = await client.documentTranslation.create({
  job_name: "chapter1",
  source_language_code: "en-IN",
  target_language_codes: ["hi-IN", "ta-IN"],
  original_filename: "chapter1.pdf",
});

// SDK does not upload the file — PUT bytes to the signed URL, then start.
await fetch(job.upload_url, {
  method: "PUT",
  headers: {
    "Content-Type": "application/pdf",
    "x-ms-blob-type": "BlockBlob",
  },
  body: fs.readFileSync("chapter1.pdf"),
});

await client.documentTranslation.start(job.job_id);

```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sarvam.ai/translate/document/jobs"

	payload := strings.NewReader("{\n  \"source_language_code\": \"en-IN\",\n  \"original_filename\": \"chapter1.pdf\",\n  \"target_language_codes\": [\n    \"hi-IN\",\n    \"ta-IN\"\n  ],\n  \"job_name\": \"chapter1\",\n  \"genre\": \"NON_FICTION\",\n  \"use_native_numerals\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-subscription-key", "<apiSubscriptionKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sarvam.ai/translate/document/jobs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-subscription-key"] = '<apiSubscriptionKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source_language_code\": \"en-IN\",\n  \"original_filename\": \"chapter1.pdf\",\n  \"target_language_codes\": [\n    \"hi-IN\",\n    \"ta-IN\"\n  ],\n  \"job_name\": \"chapter1\",\n  \"genre\": \"NON_FICTION\",\n  \"use_native_numerals\": true\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sarvam.ai/translate/document/jobs")
  .header("api-subscription-key", "<apiSubscriptionKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source_language_code\": \"en-IN\",\n  \"original_filename\": \"chapter1.pdf\",\n  \"target_language_codes\": [\n    \"hi-IN\",\n    \"ta-IN\"\n  ],\n  \"job_name\": \"chapter1\",\n  \"genre\": \"NON_FICTION\",\n  \"use_native_numerals\": true\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sarvam.ai/translate/document/jobs', [
  'body' => '{
  "source_language_code": "en-IN",
  "original_filename": "chapter1.pdf",
  "target_language_codes": [
    "hi-IN",
    "ta-IN"
  ],
  "job_name": "chapter1",
  "genre": "NON_FICTION",
  "use_native_numerals": true
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'api-subscription-key' => '<apiSubscriptionKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.sarvam.ai/translate/document/jobs");
var request = new RestRequest(Method.POST);
request.AddHeader("api-subscription-key", "<apiSubscriptionKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"source_language_code\": \"en-IN\",\n  \"original_filename\": \"chapter1.pdf\",\n  \"target_language_codes\": [\n    \"hi-IN\",\n    \"ta-IN\"\n  ],\n  \"job_name\": \"chapter1\",\n  \"genre\": \"NON_FICTION\",\n  \"use_native_numerals\": true\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "api-subscription-key": "<apiSubscriptionKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "source_language_code": "en-IN",
  "original_filename": "chapter1.pdf",
  "target_language_codes": ["hi-IN", "ta-IN"],
  "job_name": "chapter1",
  "genre": "NON_FICTION",
  "use_native_numerals": true
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sarvam.ai/translate/document/jobs")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```