Transliteration API: A Hands-on Guide

Transliteration API: A Hands-on Guide

This tutorial demonstrates how to use the Transliteration API to convert text from one script to another while preserving pronunciation. It supports multiple Indic languages and offers customizable numeral formatting.

Table of Contents

  1. Setup & Installation
  2. Authentication
  3. Understanding the Parameters
  4. Basic Usage
  5. Experimenting with Different Options
  6. Advanced Features
  7. Error Handling
  8. Additional Resources
  9. Final Notes

1. Setup & Installation

Before you begin, ensure you have the necessary Python libraries installed. Run the following commands to install the required packages:

1pip install requests
1import requests

2. Authentication

To use the API, you need an API subscription key. Follow these steps to set up your API key:

  1. Obtain your API key: If you don’t have an API key, sign up on the Sarvam AI Dashboard to get one.
  2. Replace the placeholder key: In the code below, replace “YOUR_SARVAM_AI_API_KEY” with your actual API key.
1SARVAM_API_KEY = "YOUR_SARVAM_API_KEY"

3. Understanding the Parameters

The API takes several key parameters:

  • input – The text to be transliterated.
  • source_language_code – Language of the input text.
  • target_language_code – Desired transliteration output language.
  • numerals_format – Choose between international (0-9) or native (१-९) numbers.
  • spoken_form – Whether to convert text into a natural spoken format.
  • spoken_form_numerals_language – Choose whether numbers should be spoken in English or native language.

Note: Transliteration between Indic languages (e.g., Hindi → Bengali) is not supported.

4. Basic Usage

4.1. Read the Document

We have two sample documents under the data folder:

  • sample1.txt contains an essay on The Impact of Artificial Intelligence on Society in English.
  • sample2.txt contains an essay on The Impact of Artificial Intelligence on Society in Hindi.
1def read_file(file_path, lang_name):
2 try:
3 with open(file_path, "r", encoding="utf-8") as file:
4 # Read the first 5 lines
5 lines = [next(file) for _ in range(5)]
6 print(f"=== {lang_name} Text (First Few Lines) ===")
7 print("".join(lines)) # Print first few lines
8
9 # Read the remaining content
10 remaining_text = file.read()
11
12 # Combine all text
13 full_doc = "".join(lines) + remaining_text
14
15 # Count total characters
16 total_chars = len(full_doc)
17 print(f"\nTotal number of characters in {lang_name} file:", total_chars)
18
19 return full_doc
20 except FileNotFoundError:
21 print(f"Error: {file_path} not found.")
22 return None
23 except Exception as e:
24 print(f"An error occurred while reading {file_path}: {e}")
25 return None
1# Read English and Hindi documents
2english_doc = read_file("data/sample1.txt", "English")
3hindi_doc = read_file("data/sample2.txt", "Hindi")

4.2. Split the text into chunks

Since the API has a restriction of 1000 characters per request, we need to split the text accordingly.

1def chunk_text(text, max_length=1000):
2 """Splits text into chunks of at most max_length characters while preserving word boundaries."""
3 chunks = []
4
5 while len(text) > max_length:
6 split_index = text.rfind(" ", 0, max_length) # Find the last space within limit
7 if split_index == -1:
8 split_index = max_length # No space found, force split at max_length
9
10 chunks.append(text[:split_index].strip()) # Trim spaces before adding
11 text = text[split_index:].lstrip() # Remove leading spaces for the next chunk
12
13 if text:
14 chunks.append(text.strip()) # Add the last chunk
15
16 return chunks
1# Split the text
2english_text_chunks = chunk_text(english_doc)
3
4# Display chunk info
5print(f"Total Chunks: {len(english_text_chunks)}")
6for i, chunk in enumerate(english_text_chunks[:3], 1): # Show only first 3 chunks for preview
7 print(f"\n=== Chunk {i} (Length: {len(chunk)}) ===\n{chunk}")
1# Split the text
2hindi_text_chunks = chunk_text(english_doc)
3
4# Display chunk info
5print(f"Total Chunks: {len(hindi_text_chunks)}")
6for i, chunk in enumerate(hindi_text_chunks[:3], 1): # Show only first 3 chunks for preview
7 print(f"\n=== Chunk {i} (Length: {len(chunk)}) ===\n{chunk}")

4.3. Setting up the API Endpoint

1import requests
2
3# Define API request details
4url = "https://api.sarvam.ai/transliterate"
5headers = {
6 "api-subscription-key": SARVAM_API_KEY,
7 "Content-Type": "application/json"
8}
1# Send requests for each chunk
2translated_texts = []
3for idx, chunk in enumerate(hindi_text_chunks):
4 payload = {
5 "input": chunk,
6 "source_language_code": "hi-IN",
7 "target_language_code": "hi-IN",
8 "spoken_form": True,
9 "numerals_format": "international"
10 }
11
12 response = requests.post(url, json=payload, headers=headers)
13
14 if response.status_code == 200:
15 translated_text = response.json().get("transliterated_text", "Translation not available")
16 translated_texts.append(translated_text)
17 print(f"\n=== Translated Chunk {idx + 1} ===\n{translated_text}\n")
18 else:
19 print(f"Error: {response.status_code}, {response.text}")
20
21# Combine all translated chunks
22final_translation = "\n".join(translated_texts)
23print("\n=== Final Translated Text ===")
24print(final_translation)

5. Experimenting with Different Options

We currently have three different transliteration models:

5.1. Romanization (Indic → Latin Script)

  • Converts Indic scripts to Roman script (English alphabet).
  • Example: मैं ऑफिस जा रहा हूँmain office ja raha hun
  • Parameters:
    • source_language_code = "hi-IN"
    • target_language_code = "en-IN"
1# Define the payload for Romanization (Hindi to Latin script)
2payload = {
3 "input": "मैं ऑफिस जा रहा हूँ",
4 "source_language_code": "hi-IN",
5 "target_language_code": "en-IN",
6 "spoken_form": True
7}
8
9# Send the request
10response = requests.post(url, json=payload, headers=headers)
11
12# Extract the transliterated text
13if response.status_code == 200:
14 transliterated_text = response.json().get("transliterated_text", "Translation not available")
15 print("Romanized Text:", transliterated_text)
16else:
17 print(f"Error: {response.status_code}, {response.text}")

5.2. Conversion to Indic Scripts

  • Converts text into an Indic script from various sources:

    • Code-mixed text

      • Example: मैं office जा रहा हूँमैं ऑफिस जा रहा हूँ
      • Parameters:
        • source_language_code = "hi-IN"
        • target_language_code = "hi-IN"
    • Romanized text

      • Example: main office ja raha hunमैं ऑफिस जा रहा हूँ
      • Parameters:
        • source_language_code = "hi-IN"
        • target_language_code = "hi-IN"
    • English text

      • Example: I am going to officeआइ ऍम गोइंग टू ऑफिस
      • Parameters:
        • source_language_code = "en-IN"
        • target_language_code = "hi-IN"
1payload = {
2 "input": "main office ja raha hun",
3 "source_language_code": "hi-IN",
4 "target_language_code": "hi-IN",
5 "spoken_form": True
6}
7
8# Send the request
9response = requests.post(url, json=payload, headers=headers)
10
11# Extract the transliterated text
12if response.status_code == 200:
13 transliterated_text = response.json().get("transliterated_text", "Translation not available")
14 print("Romanized Text:", transliterated_text)
15else:
16 print(f"Error: {response.status_code}, {response.text}")

5.3. Spoken Indic Form

  • Converts written text into a more natural spoken form.
  • Example: मुझे कल 9:30am को appointment हैमुझे कल सुबह साढ़े नौ बजे अपॉइंटमेंट है
1payload = {
2 "input": "मुझे कल 9:30am को appointment है",
3 "source_language_code": "hi-IN",
4 "target_language_code": "hi-IN",
5 "spoken_form": True,
6}
7
8# Send the request
9response = requests.post(url, json=payload, headers=headers)
10
11# Extract the transliterated text
12if response.status_code == 200:
13 transliterated_text = response.json().get("transliterated_text", "Translation not available")
14 print("Romanized Text:", transliterated_text)
15else:
16 print(f"Error: {response.status_code}, {response.text}")

6. Advanced Features

  • numerals_format – Choose between international (0-9) or native (१-९) numbers.
  • spoken_form_numerals_language – Choose whether numbers should be spoken in English or the native language.

6.1. Numerals Format

numerals_format is an optional parameter with two options:

  • international (default): Uses regular numerals (0-9).
  • native: Uses language-specific native numerals.

Example:

  • If international format is selected → मेरा phone number है: 9840950950.
  • If native format is selected → मेरा phone number है: ९८४०९५०९५०.
1payload = {
2 "input": "मुझे कल 9:30am को appointment है",
3 "source_language_code": "hi-IN",
4 "target_language_code": "hi-IN",
5 "spoken_form": True,
6 "numerals_format": "native"
7}
8
9# Send the request
10response = requests.post(url, json=payload, headers=headers)
11
12# Extract the transliterated text
13if response.status_code == 200:
14 transliterated_text = response.json().get("transliterated_text", "Translation not available")
15 print("Romanized Text:", transliterated_text)
16else:
17 print(f"Error: {response.status_code}, {response.text}")

6.2. Spoken Form Numerals Language

spoken_form_numerals_language is an optional parameter with two options and only works when spoken_form is true:

  • english: Numbers in the text will be spoken in English.
  • native (default): Numbers in the text will be spoken in the native language.

Example:

Input: "मेरे पास ₹200 है"

  • If english format is selected → "मेरे पास टू हन्डर्ड रूपीस है".
  • If native format is selected → "मेरे पास दो सौ रुपये है".
1payload = {
2 "input": "मुझे कल 9:30am को appointment है",
3 "source_language_code": "hi-IN",
4 "target_language_code": "hi-IN",
5 "spoken_form": True,
6 "spoken_form_numerals_language": "english"
7}
8
9# Send the request
10response = requests.post(url, json=payload, headers=headers)
11
12# Extract the transliterated text
13if response.status_code == 200:
14 transliterated_text = response.json().get("transliterated_text", "Translation not available")
15 print("Romanized Text:", transliterated_text)
16else:
17 print(f"Error: {response.status_code}, {response.text}")

7. Error Handling

You may encounter these errors while using the API:

  • 403 Forbidden (invalid_api_key_error)

  • 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.

8. Additional Resources

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

9. Final Notes

  • Keep your API key secure.
  • Use clear audio for best results.
  • Explore advanced features like diarization and translation.

Keep Building! 🚀