openapi: 3.0.1
info:
  title: Sarvam AI API
  description: >-
    REST API for Sarvam AI, India's full-stack sovereign AI platform. Provides
    chat completions over Sarvam's Indic LLMs, speech-to-text and
    speech-to-text-translate, text-to-speech, text translation,
    transliteration, and language identification across Indian languages.
    All requests authenticate with an api-subscription-key header.
  termsOfService: https://www.sarvam.ai/terms-of-service
  contact:
    name: Sarvam AI Support
    url: https://www.sarvam.ai
  version: '1.0'
servers:
  - url: https://api.sarvam.ai
security:
  - ApiSubscriptionKey: []
tags:
  - name: Chat
  - name: Speech to Text
  - name: Text to Speech
  - name: Translate
  - name: Transliterate
  - name: Language Identification
paths:
  /v1/chat/completions:
    post:
      operationId: createChatCompletion
      tags:
        - Chat
      summary: Create a chat completion
      description: >-
        Generates a model response for a conversation using Sarvam's Indic LLMs
        (sarvam-m, sarvam-30b, sarvam-105b). Supports streaming via
        Server-Sent Events when stream is true, tool use, and reasoning effort.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /speech-to-text:
    post:
      operationId: transcribeSpeech
      tags:
        - Speech to Text
      summary: Transcribe audio to text
      description: >-
        Transcribes an audio file in an Indian language using the Saaras or
        Saarika speech-recognition models. Supports auto language detection,
        word-level timestamps, and speaker diarization.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SpeechToTextRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeechToTextResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /speech-to-text-translate:
    post:
      operationId: translateSpeech
      tags:
        - Speech to Text
      summary: Transcribe and translate audio to English
      description: >-
        Transcribes Indic-language audio and translates the result into English
        in a single request using the Saaras family of models.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SpeechToTextTranslateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeechToTextResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /text-to-speech:
    post:
      operationId: convertTextToSpeech
      tags:
        - Text to Speech
      summary: Convert text to speech
      description: >-
        Synthesizes natural speech for Indian languages using the Bulbul models
        (v2, v3) with 30+ speakers and configurable pace, pitch, sample rate,
        and output audio codec. Returns base64-encoded audio.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextToSpeechRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextToSpeechResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /translate:
    post:
      operationId: translateText
      tags:
        - Translate
      summary: Translate text between Indian languages
      description: >-
        Translates text across Indian languages using Mayura (12 languages,
        multiple tones) or Sarvam-Translate (all 22 scheduled languages), with
        tone modes, output-script control, and numeral formatting.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TranslateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /transliterate:
    post:
      operationId: transliterateText
      tags:
        - Transliterate
      summary: Transliterate text between scripts
      description: >-
        Converts text between scripts while preserving the same language, with
        spoken-form conversion and international or native numeral formatting.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransliterateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransliterateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /text-lid:
    post:
      operationId: identifyLanguage
      tags:
        - Language Identification
      summary: Identify the language of text
      description: >-
        Automatically detects the language and script of input text, returning
        BCP-47 language and script codes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LanguageIdRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LanguageIdResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  securitySchemes:
    ApiSubscriptionKey:
      type: apiKey
      in: header
      name: api-subscription-key
      description: API subscription key created in the Sarvam AI dashboard.
  responses:
    Unauthorized:
      description: Missing or invalid api-subscription-key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: string
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
            - tool
        content:
          type: string
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: Sarvam LLM identifier.
          enum:
            - sarvam-m
            - sarvam-30b
            - sarvam-105b
          example: sarvam-m
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        temperature:
          type: number
          default: 0.7
        top_p:
          type: number
          default: 1
        max_tokens:
          type: integer
        stream:
          type: boolean
          default: false
          description: When true, partial deltas are streamed as Server-Sent Events.
        reasoning_effort:
          type: string
          enum:
            - low
            - medium
            - high
        frequency_penalty:
          type: number
        presence_penalty:
          type: number
        n:
          type: integer
          default: 1
        stop:
          type: array
          items:
            type: string
        seed:
          type: integer
        wiki_grounding:
          type: boolean
          description: Ground responses with Wikipedia knowledge.
        tools:
          type: array
          items:
            type: object
        tool_choice:
          oneOf:
            - type: string
            - type: object
        response_format:
          type: object
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason:
                type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
    SpeechToTextRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: >-
            Audio file (WAV, MP3, AAC, AIFF, OGG, OPUS, FLAC, MP4/M4A, AMR, WMA,
            WebM, PCM). Optimized for 16kHz.
        model:
          type: string
          enum:
            - saarika:v2.5
            - saaras:v3
          default: saarika:v2.5
        language_code:
          type: string
          description: BCP-47 code (e.g. hi-IN) or "unknown" for auto-detection.
        mode:
          type: string
          description: saaras:v3 only.
          enum:
            - transcribe
            - translate
            - verbatim
            - translit
            - codemix
        input_audio_codec:
          type: string
          description: Required only for PCM files.
          enum:
            - pcm_s16le
            - pcm_l16
            - pcm_raw
    SpeechToTextTranslateRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: Audio file to transcribe and translate to English.
        model:
          type: string
          enum:
            - saaras:v2.5
            - saaras:v3
          default: saaras:v2.5
        prompt:
          type: string
          description: Optional context to improve translation quality.
    SpeechToTextResponse:
      type: object
      properties:
        request_id:
          type: string
        transcript:
          type: string
        language_code:
          type: string
        language_probability:
          type: number
        timestamps:
          type: object
          description: Word-level timing data when requested.
        diarized_transcript:
          type: object
          description: Speaker-attributed segments when diarization is enabled.
    TextToSpeechRequest:
      type: object
      required:
        - text
        - target_language_code
      properties:
        text:
          type: string
          description: Max 2500 chars (bulbul:v3) or 1500 chars (bulbul:v2).
        target_language_code:
          type: string
          enum:
            - bn-IN
            - en-IN
            - gu-IN
            - hi-IN
            - kn-IN
            - ml-IN
            - mr-IN
            - od-IN
            - pa-IN
            - ta-IN
            - te-IN
        speaker:
          type: string
          description: Voice name; default shubh (v3) or anushka (v2).
        model:
          type: string
          enum:
            - bulbul:v2
            - bulbul:v3
          default: bulbul:v3
        pitch:
          type: number
          description: -0.75 to 0.75. bulbul:v2 only.
        pace:
          type: number
          default: 1.0
          description: v3 0.5-2.0; v2 0.3-3.0.
        loudness:
          type: number
          description: 0.3 to 3.0. bulbul:v2 only.
        speech_sample_rate:
          type: integer
          default: 24000
          enum:
            - 8000
            - 16000
            - 22050
            - 24000
            - 32000
            - 44100
            - 48000
        enable_preprocessing:
          type: boolean
          default: false
        temperature:
          type: number
          default: 0.6
          description: 0.01 to 2.0. v3 only.
        output_audio_codec:
          type: string
          default: wav
          enum:
            - mp3
            - linear16
            - mulaw
            - alaw
            - opus
            - flac
            - aac
            - wav
    TextToSpeechResponse:
      type: object
      properties:
        request_id:
          type: string
        audios:
          type: array
          items:
            type: string
            description: Base64-encoded audio.
    TranslateRequest:
      type: object
      required:
        - input
        - source_language_code
        - target_language_code
      properties:
        input:
          type: string
          description: Text to translate (up to ~1000-2000 chars).
        source_language_code:
          type: string
          description: BCP-47 code or "auto" for detection.
        target_language_code:
          type: string
        speaker_gender:
          type: string
          enum:
            - Male
            - Female
        mode:
          type: string
          enum:
            - formal
            - modern-colloquial
            - classic-colloquial
            - code-mixed
        model:
          type: string
          enum:
            - mayura:v1
            - sarvam-translate:v1
        output_script:
          type: string
          enum:
            - roman
            - fully-native
            - spoken-form-in-native
        numerals_format:
          type: string
          enum:
            - international
            - native
          default: international
    TranslateResponse:
      type: object
      properties:
        request_id:
          type: string
        translated_text:
          type: string
        source_language_code:
          type: string
    TransliterateRequest:
      type: object
      required:
        - input
        - source_language_code
        - target_language_code
      properties:
        input:
          type: string
        source_language_code:
          type: string
        target_language_code:
          type: string
        numerals_format:
          type: string
          enum:
            - international
            - native
          default: international
        spoken_form:
          type: boolean
          default: false
        spoken_form_numerals_language:
          type: string
          enum:
            - english
            - native
          default: native
    TransliterateResponse:
      type: object
      properties:
        request_id:
          type: string
        transliterated_text:
          type: string
        source_language_code:
          type: string
    LanguageIdRequest:
      type: object
      required:
        - input
      properties:
        input:
          type: string
    LanguageIdResponse:
      type: object
      properties:
        request_id:
          type: string
        language_code:
          type: string
        script_code:
          type: string