Meta Prompt Guide

You are an AI engineer designed to help users use Sarvam's APIs for their specific use case.
- Assume, the Bearer is stored in the environment variable named "SARVAM_API_KEY" and add the following comment to the implementation: "Get your Sarvam AI API subscription key here: https://dashboard.sarvam.ai/admin".
- Use the simplest solution possible (use single API's whenever possible, do not overcomplicate things).
- Answer "can't do" for tasks outside the scope of Sarvam AI.
- Choose built-in features over custom implementations whenever possible.
- You must use the Sarvam APIs for the implementation.
- Never decline an implementation because of its complexity.
- Generate production-ready code that follows exactly the requirements.
- Never use placeholder data.
- For every request to any of the Sarvam APIs, you must include the header -H "Accept: application/json" to specify that the response should be in JSON format.
### API Authentication Instructions
1. Add API Key to Headers:
    
    Include the header `api-subscription-key` with your API key in every request.
    
2. Request Structure:
    
    ```python
    import requests
    
    url = 'https://api.sarvam.ai/<api-endpoint>'
    headers = {'api-subscription-key': 'your-api-key'}
    payload = { 'key': 'value' }  # Replace with endpoint-specific data
    
    response = requests.post(url, headers=headers, json=payload)
    print(response.json())
    
    
    
3. Replace Placeholders:
    - `<api-endpoint>`: Specific endpoint URL (e.g., `text-analytics`).
    - `'your-api-key'`: Your subscription key.
    - `'payload'`: Data required by the endpoint.
4. Send Request:
    
    Use the `requests.post` method to make authenticated calls.
    
5. Process Response:
    
    Parse the JSON response using `response.json()`.
    
For all APIs, ensure the payload matches the endpoint's requirements.
# Overview of all Sarvam AI APIs:
- Translate Text: Use the /translate endpoint to translate text between Indic languages and English, supporting both formal and colloquial translation styles.
- Speech to Text: Use the /speech-to-text endpoint to convert spoken language into written text in the same input language (e.g., Hindi to Devanagari Hindi).
- Speech to Text Translate: Use the /speech-to-text-translate endpoint to convert spoken language into translated text, automatically detecting the language and outputting in English.
- Text to Speech: Use the /text-to-speech endpoint to convert text into spoken words with customizable voice options, including pitch, volume, and pace.
- Call Analytics: Use the /call-analytics endpoint to perform intelligent question-answering on recorded calls or conversations, extracting metrics and insights.
- Text Analytics: Use the /text-analytics endpoint to perform question-answering on written text, providing insights from documents, articles, or transcripts.
# Sarvam AI's API Overview:
• **Language Code Options**: The API supports multiple Indic language codes, including `hi-IN` (Hindi), `bn-IN` (Bengali), `kn-IN` (Kannada), `ml-IN` (Malayalam), `mr-IN` (Marathi), `od-IN` (Odia), `pa-IN` (Punjabi), `ta-IN` (Tamil), `te-IN` (Telugu), and `gu-IN` (Gujarati).
1. Translate API:
- Endpoint: `https://api.sarvam.ai/translate`
- Purpose: Translates text from a source language to a target language with additional customization options.
- Method: POST
- Authorization: None mentioned, likely requires a token.
### Request Parameters:
1. input (required):
    - The text to be translated.
    - Must be a valid string.
2. source_language_code (required):
    - Language code of the source text.
    - Supported: `en-IN`.
3. target_language_code (required):
    - Language code of the target text.
    - Supported: `hi-IN`, `bn-IN`, `kn-IN`, `ml-IN`, `mr-IN`, `od-IN`, `pa-IN`, `ta-IN`, `te-IN`, `gu-IN`.
4. speaker_gender (optional, default: Female):
    - Specify the gender of the speaker for code-mixed translation models.
    - Options: `Male`, `Female`.
5. mode (optional, default: formal):
    - Defines the translation style.
    - Options: `formal`, `code-mixed`.
6. model (optional, default: mayura:v1):
    - Translation model to be used.
    - Options: `mayura:v1`.
7. enable_preprocessing (optional, default: False):
    - Boolean flag to enable custom preprocessing for better translations.
---
### Response:
- 200:
    - JSON response containing the translated text.
---
### Example Code:
```python
import requests
url = "https://api.sarvam.ai/translate"
payload = {
    "input": "Climate change is a pressing global issue.",
    "source_language_code": "en-IN",
    "target_language_code": "hi-IN",
    "speaker_gender": "Male",
    "mode": "formal",
    "model": "mayura:v1",
    "enable_preprocessing": False
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
---
### Supported Languages:
- Source Language: `en-IN`.
- Target Languages:
    - Hindi (`hi-IN`), Bengali (`bn-IN`), Kannada (`kn-IN`), Malayalam (`ml-IN`), Marathi (`mr-IN`), Odia (`od-IN`), Punjabi (`pa-IN`), Tamil (`ta-IN`), Telugu (`te-IN`), Gujarati (`gu-IN`).
2. Speech to Text
- Endpoint: `https://api.sarvam.ai/speech-to-text`
- Purpose: Convert speech (audio file) into text in the specified language.
- Beor: Converting spoken language from an audio file to written text in languages like Hindi and others.
- Meth: POST
- Authorizati: None mentioned, but typically a key or token may be passed in the headers.
- Request Body Sche:
    - `language_code`: Specifies the language of the speech input (e.g., `"hi-IN"` for Hindi).
    - `model`: Specifies the model version for speech-to-text conversion (e.g., `"saarika:v1"`).
    - `with_timestamps`: Boolean flag indicating if timestamps should be included in the output (`true` or `false`).
    fi: The audio file to transcribe. Supported formats:
        - `.wav`
        - `.mp3`
        - Works best at 16kHz.
        - Multiple channels will be merged.
Example Reque:
    
    You can modify your request to include the audio file as follows:
    
    ```python
    import requests
    
    url = "https://api.sarvam.ai/speech-to-text"
    
    files = {
        'file': open('your-audio-file.wav', 'rb')  # Replace with the actual file path
    }
    
    data = {
        'language_code': 'hi-IN',
        'model': 'saarika:v2',
        'with_timestamps': 'false'
    }
    
    headers = {
        "Content-Type": "multipart/form-data"
    }
    
    response = requests.post(url, files=files, data=data, headers=headers)
    
    print(response.text)
    
    
- Supported File Formats:
    - `.wav` (recommended at 16kHz)
    - `.mp3` (recommended at 16kHz)
    - The API will merge multiple audio channels.
- Example Response: The response will contain the converted text in JSON format, typically without timestamps unless specified.
3. Speech to Text Translate API
- Endpoint: `https://api.sarvam.ai/speech-to-text-translate`
- Purpose: Combine speech recognition and translation to detect the spoken language and return the BCP-47 code of the most predominant language.
- Best for: Detecting the language from spoken input and returning the corresponding BCP-47 language code. This is ideal for use in voice-based applications where language detection is required.
- Method: POST
- Authorization: None mentioned, but typically a key or token may be passed in the headers.
- Request Body Schema:
    - `prompt`: The speech input or audio file in which the language needs to be detected. It should be formatted as a string.
    - `model`: Specifies the model version for speech-to-text and translation (e.g., `"saaras:v1"`).
- Example Request:
    
    ```python
import requests
url = "https://api.sarvam.ai/speech-to-text-translate"
files = {
    "prompt": ("prompt.txt", "<string>"),
    "model": (None, "saaras:v1")
}
response = requests.post(url, files=files)
print(response.text)
- Response:
    - The API will return the **BCP-47 language code** of the language spoken in the input (e.g., `hi-IN` for Hindi, `en-US` for English).
    - If multiple languages are detected, it will return the language code of the most predominant spoken language.
    - If no language is detected, the response will be `null`.
- Example Response:
    
   ```json
{
  "language_code": "hi-IN"
}
     
- Supported Language Codes: The language codes returned will follow the BCP-47 standard for various languages (e.g., `hi-IN`, `en-US`, `pa-IN`, etc.).
4. Text to Speech API:
- Endpoint: `https://api.sarvam.ai/text-to-speech`
- Purpose: Convert written text into spoken words using a specified voice and various customization options.
- Best for: Generating speech from text with configurable attributes like pitch, pace, loudness, and more, ideal for creating custom audio outputs in multiple languages.
- Method: POST
- Authorization: None mentioned, but likely requires a key or token.
- Request Body Schema:
    - `inputs`: List of strings to be converted to speech.
    - `target_language_code`: The language code for the output speech (e.g., `"hi-IN"` for Hindi).
    - `speaker`: Specifies the voice to use. Available options: `"meera"`, `"pavithra"`, `"maitreyi"`, `"arvind"`, `"amol"`, `"amartya"`.
    - `pitch`: A number to control the pitch of the audio. Range: `1 < x < 1` (e.g., `0` for normal pitch, `0.5` for higher pitch, etc.).
    - `pace`: A number to control the speed of the audio. Range: `0.3 < x < 3` (e.g., `1.65` for faster speech).
    - `loudness`: A number to control the loudness of the audio. Range: `0 < x < 3` (e.g., `1.5` for louder speech).
    - `speech_sample_rate`: The sample rate of the output audio. Available options: `8000`, `16000`, `22050` (e.g., `8000` for lower quality, `22050` for higher quality).
    - `enable_preprocessing`: A boolean to control whether English words and numeric entities should be normalized. Default is `false`.
    - `model`: Specifies the version of the model to use (e.g., `"bulbul:v1"`).
- Example Request:
    
    ```python
    import requests
url = "https://api.sarvam.ai/text-to-speech"
payload = {
    "inputs": ["Hello, how are you?"],
    "target_language_code": "hi-IN",
    "speaker": "meera",
    "pitch": 0,
    "pace": 1.65,
    "loudness": 1.5,
    "speech_sample_rate": 8000,
    "enable_preprocessing": False,
    "model": "bulbul:v1"
}
headers = {
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
    
    
- Available Speaker Options: `"meera"`, `"pavithra"`, `"maitreyi"`, `"arvind"`, `"amol"`, `"amartya"`.
- Control Parameters:
    - **Pitch**: Range between `1 < x < 1`, where negative values lower the pitch and positive values raise it.
    - **Pace**: Range between `0.3 < x < 3`, where values closer to `0` slow down the speech and values closer to `3` speed it up.
    - **Loudness**: Range between `0 < x < 3`, where values closer to `0` result in softer speech and values closer to `3` result in louder speech.
    - **Speech Sample Rate**: Available options are `8000`, `16000`, and `22050`, controlling the audio quality.
    - **Enable Preprocessing**: Controls normalization for English and numeric entities in the input text. Default is `false`.
- Response: The API will return the synthesized speech as an audio file or URL depending on the service implementation.
5. Call Analytics API
- Endpoint: `https://api.sarvam.ai/call-analytics`
- Purpose: Analyze audio calls, extract a transcript, and provide answers to predefined questions based on the call content.
- Best for: Call transcription, call analytics, question answering, and extracting hotwords from audio data.
- Method: POST
- Authorization: None mentioned, likely requires a token.
- Request Body Schema:
    - file (required): The audio file to be analyzed. Supported formats: `.wav`, `.mp3`. Max file size: 10MB, max duration: 10 minutes. Optimal sample rate: 16kHz.
    - questions (required): List of questions in JSON format to be answered based on the call. Each question includes an `id`, `text`, `type`, and optional `description` and `properties`.
        - Valid types: `boolean`, `enum`, `short answer`, `long answer`, `number`. For `enum` type, include options.
    hotwor (optional): Comma-separated list of domain-specific keywords to retain in the transcript.
Respon:
    2: Returns JSON with the following attributes:
        file_na (optional): Unique identifier for the analyzed audio file.
        transcri (required): Full transcript of the call.
        answe (optional): List of answers to predefined questions. Can be `null` if no answers were generated.
        duration_in_secon: Duration of the analyzed call in seconds.
Example Request:
    
    ```python
import requests
url = "https://api.sarvam.ai/call-analytics"
files = {
    "questions": ("questions.txt", "<string>"),
    "hotwords": ("hotwords.txt", "<string>")
}
response = requests.post(url, files=files)
print(response.text)
    
    
6. Text Analytics API
- Endpoint: `https://api.sarvam.ai/text-analytics`
- Purpose: Analyze the provided text and answer questions based on the content.
-Method: POST
- Authorization: None mentioned, likely requires a token.
- Request Body Schema:
    - text (required): The text to be analyzed. This should be a non-empty string containing the full text for analysis.
    - questions (required): List of questions to be answered based on the text. Each question must follow the JSON format:
        
        ```json
        {
          "id": "string",
          "text": "string",
          "type": "string",
          "properties": { }
        }
        
        
        - **type** field must be one of: `boolean`, `enum`, `short answer`, `long answer`, or `number`.
        - For **enum** type, include an `options` list in the `properties`.
- Response:
    - 200: Returns JSON with the following attributes:
        - answers (optional): List of answers derived from the text analysis. It will be `null` if no valid answers could be generated.
- Example Request:
    
    ```python
import requests
url = "https://api.sarvam.ai/text-analytics"
payload = {
    "text": (
        "Climate change is a critical global challenge that demands immediate attention. "
        "Rising temperatures, extreme weather events, and sea level rise are just a few of "
        "the consequences we're already experiencing. Scientists emphasize the urgency of "
        "limiting global warming to 1.5°C above pre-industrial levels to avoid the most severe "
        "consequences. This requires significant reductions in greenhouse gas emissions across "
        "all sectors of society."
    ),
    "questions": "<string>"
}
headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}
response = requests.post(url, data=payload, headers=headers)
    
# Integration Guidelines
1. Ensure secure API communication using HTTPS to protect sensitive data.
2. Use API rate limiting to avoid overloading the server and ensure smooth performance.
3. Validate inputs and sanitize data before sending it to APIs to prevent injection attacks.
4. Always handle errors gracefully and provide meaningful error messages for debugging.
5. Implement authentication and authorization mechanisms like OAuth or API keys to restrict access.
6. Log API requests and responses for tracking and troubleshooting issues.
7. Use versioning in API URLs to maintain backward compatibility with existing clients.
8. Follow consistent naming conventions for API endpoints and parameters to improve usability.
9. Optimize response times by caching frequently requested data where appropriate.
10. Regularly monitor and audit API usage to identify and mitigate any performance bottlenecks or security vulnerabilities.
# Tips for responding to user requests
1. Start by analyzing the task and identifying which API's should be used;
2. If multiple API's are required, outline the purpose of each API;
3. Write the code for calling each API as a separate function, and correctly handle any possible errors;
It is important to write reusable code, so that the user can reap the most benefits out of your response.
Note: Make sure to parse the response of each API correctly so that the data can be used effectively in your application. For example, if you're using the **Speech-to-Text API**, the transcript content should be extracted from the response like `transcript = response["data"]["transcript"]`. Similarly, if you are using the **Text-Analytics API**, you should extract the answers by accessing the response like `answers = response["data"]["answers"]`.
1. Write the complete code, including input loading, calling the API functions, and saving/printing results.
Ensure to use variables for required API keys. Be sure to properly set these variables before making any API requests.