> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prem.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Encrypted Audio Transcriptions (RVENC)

> Simple pass-through to enclave audio transcription endpoint with encrypted payload. Rvenc = raw volatile encrypted. Accepts an encrypted audio file and inference parameters. Transcribes audio into the input language. Only provides authentication, security checks, and rate limiting. No file storage or custom features.

# TypeScript SDK

The SDK is available on GitHub: [premAI-io/api-sdk-ts](https://github.com/premAI-io/api-sdk-ts)

## Usage

### Basic Setup

Create a client with auto-generated encryption keys:

```typescript theme={"system"}
import createRvencClient from "@premai/api-sdk";
import fs from "fs";

const client = await createRvencClient({
  apiKey: process.env.API_KEY,
  clientKEK: process.env.CLIENT_KEK
});
```

### Pre-generate Keys

You can pre-generate encryption keys and reuse them:

```typescript theme={"system"}
import createRvencClient, { generateEncryptionKeys } from "@premai/api-sdk";

const encryptionKeys = await generateEncryptionKeys();

const client = await createRvencClient({
  apiKey: process.env.API_KEY,
  encryptionKeys,
  requestTimeoutMs: 60000,  // optional
  maxBufferSize: 20 * 1024 * 1024, // optional
});
```

### Basic Transcription

```typescript theme={"system"}
const transcription = await client.audio.transcriptions.create({
  file: fs.createReadStream('./audio.wav'),
  model: 'openai/whisper-large-v3',
});

console.log(transcription.text);
```

### Transcription with Options

```typescript theme={"system"}
const transcription = await client.audio.transcriptions.create({
  file: fs.createReadStream('./audio.mp3'),
  model: 'openai/whisper-large-v3',
  language: 'en',
  prompt: 'This is a discussion about artificial intelligence.',
  response_format: 'verbose_json',
  temperature: 0,
  timestamp_granularities: ['word', 'segment'],
});
```

## Configuration

| Option                    | Default     | Description                                            |
| ------------------------- | ----------- | ------------------------------------------------------ |
| `file`                    | required    | Audio file (ReadStream, Buffer, Blob, etc.)            |
| `model`                   | required    | Model ID (e.g., `'openai/whisper-large-v3'`)           |
| `language`                | auto-detect | ISO-639-1 language code (e.g., `'en'`, `'de'`, `'fr'`) |
| `prompt`                  | optional    | Text prompt to guide the model                         |
| `response_format`         | `'json'`    | Format: `'json'`, `'text'`, or `'verbose_json'`        |
| `temperature`             | `0`         | Sampling temperature (0-1)                             |
| `timestamp_granularities` | optional    | Array of `'word'` and/or `'segment'` for timestamps    |

> **Note:** `openai/whisper-large-v3` model supports non-streaming only.

## OpenAI-Compatible API Server

Run as a standalone server with automatic DEK store management per API key:

```bash theme={"system"}
npm start
# Server runs on http://localhost:3000
```

Use with any OpenAI-compatible client:

```bash theme={"system"}
curl http://localhost:3000/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@audio.mp3" \
  -F "model=openai/whisper-large-v3"
```

Or use the SDK directly in Node.js:

```typescript theme={"system"}
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.API_KEY,
  baseURL: "http://localhost:3000/v1",
});

const transcription = await client.audio.transcriptions.create({
  file: fs.createReadStream('./audio.mp3'),
  model: 'openai/whisper-large-v3',
});

console.log(transcription.text);
```

The server caches clients in memory per API key for better performance.

***


## OpenAPI

````yaml post /rvenc/audio/transcriptions
openapi: 3.1.0
info:
  title: Prem API
  description: Full description of private and dev-availble API endpoints
  version: 1.0.0
  termsOfService: https://prem.io/terms
  contact:
    name: API Support
    url: https://help.prem.io
    email: support@premai.io
servers:
  - url: https://gateway.prem.io
    description: Production API server
security: []
paths:
  /rvenc/audio/transcriptions:
    post:
      tags:
        - Audio
        - dev-api
      summary: Encrypted Audio Transcriptions (RVENC)
      description: >-
        Simple pass-through to enclave audio transcription endpoint with
        encrypted payload. Rvenc = raw volatile encrypted. Accepts an encrypted
        audio file and inference parameters. Transcribes audio into the input
        language. Only provides authentication, security checks, and rate
        limiting. No file storage or custom features.
      operationId: createRvencAudioTranscription
      requestBody:
        $ref: '#/components/requestBodies/createRvencAudioTranscriptionRequest'
      responses:
        '200':
          $ref: '#/components/responses/createRvencAudioTranscriptionResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '413':
          description: Request entity too large - audio file exceeds maximum allowed size
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    examples:
                      - 413
                  error:
                    type: string
                    examples:
                      - >-
                        Audio file size exceeds the maximum allowed limit of
                        25MB.
        '429':
          description: Too many requests - rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    examples:
                      - 429
                  error:
                    type: string
                    examples:
                      - Rate limit exceeded. Please try again later.
      security:
        - BearerAuth: []
          ApiKeyAuth: []
components:
  requestBodies:
    createRvencAudioTranscriptionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/createRvencAudioTranscriptionRequest'
  responses:
    '400':
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                enum:
                  - 400
                  - 401
                  - 403
                  - 404
                description: Status code of the response
              data:
                type:
                  - object
                  - 'null'
                description: Response data containing the requested object
              error:
                type:
                  - string
                  - 'null'
                examples:
                  - Some error message
                description: Error message of the response, human readable
              message:
                type: 'null'
              env:
                type: string
                enum:
                  - development
                  - production
                description: API environment
              log:
                type:
                  - string
                  - object
                  - 'null'
                examples:
                  - request_id: req_1234567890
                  - Some pertinent log message
                description: Useful informaiton, not always present, to debug the response
              validator:
                type:
                  - object
                  - array
                  - 'null'
                examples:
                  - email: Invalid email address
                    password: Password is required
                description: >-
                  Validator response object, each key is the field name and
                  value is the error message
              support_id:
                type:
                  - string
                  - 'null'
                format: uuid
                examples:
                  - support_uuidv7-something-else
                description: >-
                  Support ID linked to the response, used to identify it when
                  talking with our team
            required:
              - status
              - error
              - message
              - env
              - log
              - support_id
            additionalProperties: false
    '401':
      description: Access token is missing or invalid
      content:
        application/json:
          schema:
            allOf:
              - type: object
                properties:
                  status:
                    type: integer
                    enum:
                      - 400
                      - 401
                      - 403
                      - 404
                    description: Status code of the response
                  data:
                    type:
                      - object
                      - 'null'
                    description: Response data containing the requested object
                  error:
                    type:
                      - string
                      - 'null'
                    examples:
                      - Some error message
                    description: Error message of the response, human readable
                  message:
                    type: 'null'
                  env:
                    type: string
                    enum:
                      - development
                      - production
                    description: API environment
                  log:
                    type:
                      - string
                      - object
                      - 'null'
                    examples:
                      - request_id: req_1234567890
                      - Some pertinent log message
                    description: >-
                      Useful informaiton, not always present, to debug the
                      response
                  validator:
                    type:
                      - object
                      - array
                      - 'null'
                    examples:
                      - email: Invalid email address
                        password: Password is required
                    description: >-
                      Validator response object, each key is the field name and
                      value is the error message
                  support_id:
                    type:
                      - string
                      - 'null'
                    format: uuid
                    examples:
                      - support_uuidv7-something-else
                    description: >-
                      Support ID linked to the response, used to identify it
                      when talking with our team
                required:
                  - status
                  - error
                  - message
                  - env
                  - log
                  - support_id
                additionalProperties: false
              - properties:
                  status:
                    type: integer
                    enum:
                      - 401
    '403':
      description: You do not have the required permissions to access this resource
      content:
        application/json:
          schema:
            allOf:
              - type: object
                properties:
                  status:
                    type: integer
                    enum:
                      - 400
                      - 401
                      - 403
                      - 404
                    description: Status code of the response
                  data:
                    type:
                      - object
                      - 'null'
                    description: Response data containing the requested object
                  error:
                    type:
                      - string
                      - 'null'
                    examples:
                      - Some error message
                    description: Error message of the response, human readable
                  message:
                    type: 'null'
                  env:
                    type: string
                    enum:
                      - development
                      - production
                    description: API environment
                  log:
                    type:
                      - string
                      - object
                      - 'null'
                    examples:
                      - request_id: req_1234567890
                      - Some pertinent log message
                    description: >-
                      Useful informaiton, not always present, to debug the
                      response
                  validator:
                    type:
                      - object
                      - array
                      - 'null'
                    examples:
                      - email: Invalid email address
                        password: Password is required
                    description: >-
                      Validator response object, each key is the field name and
                      value is the error message
                  support_id:
                    type:
                      - string
                      - 'null'
                    format: uuid
                    examples:
                      - support_uuidv7-something-else
                    description: >-
                      Support ID linked to the response, used to identify it
                      when talking with our team
                required:
                  - status
                  - error
                  - message
                  - env
                  - log
                  - support_id
                additionalProperties: false
              - properties:
                  status:
                    type: integer
                    enum:
                      - 403
    createRvencAudioTranscriptionResponse:
      description: >-
        Encrypted audio transcription response. The response contains the
        encrypted transcription result which must be decrypted using the shared
        secret derived from the request's cipherText, along with the response
        nonce.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/Response200'
              - type: object
                properties:
                  data:
                    $ref: '#/components/schemas/createRvencAudioTranscriptionResponse'
  schemas:
    createRvencAudioTranscriptionRequest:
      type: object
      description: >-
        Request body for rvenc (raw volatile encrypted) audio transcription.
        Contains an encrypted payload with cryptographic materials needed for
        decryption.
      properties:
        encryptedInference:
          type: string
          description: >-
            Encrypted JSON string containing all audio transcription parameters.
            When decrypted, this string must match the structure shown in the
            expandable `_decryptedInference` property below (reference only - do
            not send this property).
        _decryptedInference:
          $ref: '#/components/schemas/rvencAudioTranscriptionInferenceParams'
          description: >-
            **Reference only - Do NOT send this property** - This shows the
            structure that `encryptedInference` should contain when decrypted.
            Encrypt a JSON object matching this structure and send it as the
            `encryptedInference` string.
          readOnly: true
        cipherText:
          type: string
          description: Cipher text for shared secret generation (ECDH key exchange)
        nonce:
          type: string
          description: Nonce used for encrypting the inference payload
        encryptedFileName:
          type: string
          description: >-
            The encrypted audio file name. The file name is encrypted using
            XChaCha20-Poly1305 with the shared secret and fileNameNonce.
        fileNameNonce:
          type: string
          description: Nonce used for encrypting the encrypted audio file name
        encryptedFile:
          type: string
          description: >-
            The encrypted audio file data. The audio content is encrypted using
            XChaCha20-Poly1305 with the shared secret and fileNonce.
        fileNonce:
          type: string
          description: Nonce used for encrypting the encrypted audio file
      required:
        - encryptedInference
        - cipherText
        - nonce
        - fileNameNonce
        - encryptedFileName
        - fileNonce
        - encryptedFile
      additionalProperties: false
      examples:
        - encryptedInference: encrypted_inference_payload_data
          cipherText: cipher_text_for_key_exchange
          nonce: nonce_value
          fileNameNonce: file_name_nonce_value
          encryptedFileName: encrypted_audio_file_name_data
          fileNonce: file_nonce_value
          encryptedFile: encrypted_audio_file_data
    Response200:
      type: object
      properties:
        status:
          type: integer
          enum:
            - 200
            - 201
            - 202
          description: Status code of the response
        data:
          type:
            - object
            - array
            - 'null'
          description: Response data containing the requested object
        error:
          type:
            - string
            - 'null'
          examples:
            - Invalid email address
          description: Error message of the response, human readable
        message:
          type:
            - string
            - 'null'
          examples:
            - Resource created successfully
          description: Message of the response, human readable
        env:
          type: string
          enum:
            - development
            - production
          description: API environment
        log:
          type:
            - string
            - object
            - 'null'
          examples:
            - request_id: req_1234567890
            - Some pertinent log message
          description: Useful informaiton, not always present, to debug the response
        validator:
          type:
            - object
            - array
            - 'null'
          examples:
            - email: Invalid email address
              password: Password is required
          description: >-
            Validator response object, each key is the field name and value is
            the error message
        support_id:
          type:
            - string
            - 'null'
          format: uuid
          examples:
            - support_uuidv7-something-else
          description: >-
            Support ID linked to the response, used to identify it when talking
            with our team
      required:
        - status
        - data
        - message
        - env
      examples:
        - status: 200
          data:
            id: '123'
          error: null
          log: null
          validator: null
          support_id: null
          message: Resource created successfully
          env: development
    createRvencAudioTranscriptionResponse:
      type: object
      description: >-
        Encrypted audio transcription response. Contains the encrypted
        transcription result that must be decrypted using the shared secret
        derived from the request's cipherText.
      properties:
        encryptedResponse:
          type: string
          description: >-
            Encrypted JSON string containing the transcription result. Decrypt
            using XChaCha20-Poly1305 with the shared secret (derived from
            cipherText) and the response nonce. When decrypted, the content
            matches the structure shown in the `_decryptedResponse` property
            below (reference only).
        nonce:
          type: string
          description: Hex-encoded nonce used for decrypting the encryptedResponse payload.
        _decryptedResponse:
          $ref: '#/components/schemas/rvencTranscriptionDecryptedResponse'
          description: >-
            **Reference only - This is NOT returned in the response.** This
            shows the structure that `encryptedResponse` contains when
            decrypted. The decrypted content matches OpenAI's Transcription
            response structure.
          readOnly: true
      required:
        - encryptedResponse
        - nonce
      examples:
        - encryptedResponse: >-
            a1b2c3d4e5f67890abcdef1234567890abcdef123456789012345678901234567890abcdef...
          nonce: f6e5d4c3b2a19876543210fedcba9876
    rvencAudioTranscriptionInferenceParams:
      type: object
      description: >-
        Decrypted inference parameters that are encrypted and sent as
        encryptedInference for audio transcription. This schema documents the
        structure of the JSON that should be encrypted and included in the
        encryptedInference field.
      properties:
        model:
          type: string
          description: >-
            ID of the model to use. Only openai/whisper-large-v3 is currently
            available.
          enum:
            - openai/whisper-large-v3
        language:
          type: string
          description: >-
            The language of the input audio. Supplying the input language in
            ISO-639-1 format will improve accuracy and latency. Optional, not
            applicable for openai/whisper-large-v3 models which auto-detect
            language.
          examples:
            - en
            - es
            - fr
            - de
            - ja
            - zh
        prompt:
          type: string
          description: >-
            An optional text to guide the model's style or continue a previous
            audio segment. The prompt should match the audio language for
            openai/whisper-large-v3. For openai/whisper-large-v3 models, the
            prompt can be used to provide additional context or instructions.
        response_format:
          type: string
          enum:
            - json
            - text
            - verbose_json
          default: json
          description: >-
            The format of the output. Options: json (default), text (plain
            text), verbose_json (JSON with additional metadata like word
            timestamps).
        temperature:
          type: number
          minimum: 0
          maximum: 1
          default: 0
          description: >-
            The sampling temperature, between 0 and 1. Higher values like 0.8
            will make the output more random, while lower values like 0.2 will
            make it more focused and deterministic. If set to 0, the model will
            use log probability to automatically increase the temperature until
            certain thresholds are hit.
        timestamp_granularities:
          type: array
          items:
            type: string
            enum:
              - word
              - segment
          description: >-
            The timestamp granularities to populate for this transcription.
            response_format must be set to verbose_json to use timestamp
            granularities. Either or both of these options are supported: word,
            or segment. Note: There is no additional latency for segment
            timestamps, but generating word timestamps incurs additional
            latency.
      required:
        - model
      additionalProperties: false
      examples:
        - model: openai/whisper-large-v3
          language: en
          response_format: json
        - model: openai/whisper-large-v3
          language: es
          prompt: This is a conversation about technology.
          temperature: 0.2
          response_format: text
    rvencTranscriptionDecryptedResponse:
      type: object
      description: >-
        Decrypted audio transcription result matching OpenAI's Transcription
        response. When `encryptedResponse` is decrypted, it will match this
        structure.
      properties:
        text:
          type: string
          description: The transcribed text of the audio.
          examples:
            - Hello world
        task:
          type: string
          description: The task performed, typically 'transcribe'. (Verbose JSON only)
          examples:
            - transcribe
        language:
          type: string
          description: The detected or specified language. (Verbose JSON only)
          examples:
            - english
        duration:
          type: number
          description: The duration of the audio in seconds. (Verbose JSON only)
          examples:
            - 2.5
        segments:
          type: array
          description: >-
            Segments of the transcribed text with timestamps. (Verbose JSON
            only, if requested)
          items:
            type: object
            properties:
              id:
                type: integer
              seek:
                type: integer
              start:
                type: number
              end:
                type: number
              text:
                type: string
              tokens:
                type: array
                items:
                  type: integer
              temperature:
                type: number
              avg_logprob:
                type: number
              compression_ratio:
                type: number
              no_speech_prob:
                type: number
        words:
          type: array
          description: Word-level timestamps. (Verbose JSON only, if requested)
          items:
            type: object
            properties:
              word:
                type: string
              start:
                type: number
              end:
                type: number
      required:
        - text
      additionalProperties: false
      examples:
        - text: The quick brown fox jumps over the lazy dog.
        - task: transcribe
          language: english
          duration: 5.2
          text: The quick brown fox jumps over the lazy dog.
          segments:
            - id: 0
              seek: 0
              start: 0
              end: 5.2
              text: The quick brown fox jumps over the lazy dog.
              tokens:
                - 50364
                - 464
                - 2068
                - 7586
                - 21831
                - 11687
                - 625
                - 262
                - 16931
                - 3290
                - 13
                - 50624
              temperature: 0
              avg_logprob: -0.2
              compression_ratio: 1.2
              no_speech_prob: 0.1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Send your access token as header Authorization: Bearer {accessToken}'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Your API key that starts with sk_live or sk_test. You can create yours
        at go.prem.io/api-keys.

````