> ## 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 Translations (RVENC)

> Simple pass-through to enclave audio translation endpoint with encrypted payload. Rvenc = raw volatile encrypted. Accepts an encrypted audio file and inference parameters. Translates audio into English text regardless of 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 Translation

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

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

### Translation with Options

```typescript theme={"system"}
const translation = await client.audio.translations.create({
  file: fs.createReadStream('./german.mp3'),
  model: 'openai/whisper-large-v3',
  prompt: 'Discussion about renewable energy sources.',
  response_format: 'verbose_json',
  temperature: 0.2,
});
```

## Configuration

| Option            | Default  | Description                                     |
| ----------------- | -------- | ----------------------------------------------- |
| `file`            | required | Audio file (ReadStream, Buffer, Blob, etc.)     |
| `model`           | required | Model ID (e.g., `'openai/whisper-large-v3'`)    |
| `prompt`          | optional | Text prompt to guide the model                  |
| `response_format` | `'json'` | Format: `'json'`, `'text'`, or `'verbose_json'` |
| `temperature`     | `0`      | Sampling temperature (0-1)                      |

> **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/translations \
  -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 translation = await client.audio.translations.create({
  file: fs.createReadStream('./audio.mp3'),
  model: 'openai/whisper-large-v3',
});

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

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

***


## OpenAPI

````yaml post /rvenc/audio/translations
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/translations:
    post:
      tags:
        - Audio
        - dev-api
      summary: Encrypted Audio Translations (RVENC)
      description: >-
        Simple pass-through to enclave audio translation endpoint with encrypted
        payload. Rvenc = raw volatile encrypted. Accepts an encrypted audio file
        and inference parameters. Translates audio into English text regardless
        of the input language. Only provides authentication, security checks,
        and rate limiting. No file storage or custom features.
      operationId: createRvencAudioTranslation
      requestBody:
        $ref: '#/components/requestBodies/createRvencAudioTranslationRequest'
      responses:
        '200':
          $ref: '#/components/responses/createRvencAudioTranslationResponse'
        '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:
    createRvencAudioTranslationRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/createRvencAudioTranslationRequest'
  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
    createRvencAudioTranslationResponse:
      description: >-
        Encrypted audio translation response. The response contains the
        encrypted translation result (always to English) 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/createRvencAudioTranslationResponse'
  schemas:
    createRvencAudioTranslationRequest:
      type: object
      description: >-
        Request body for rvenc (raw volatile encrypted) audio translation.
        Contains an encrypted payload with cryptographic materials needed for
        decryption.
      properties:
        encryptedInference:
          type: string
          description: >-
            Encrypted JSON string containing all audio translation 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/rvencAudioTranslationInferenceParams'
          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
    createRvencAudioTranslationResponse:
      type: object
      description: >-
        Encrypted audio translation response. Contains the encrypted translation
        result (always translated to English) that must be decrypted using the
        shared secret derived from the request's cipherText.
      properties:
        encryptedResponse:
          type: string
          description: >-
            Encrypted JSON string containing the translation 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/rvencTranslationDecryptedResponse'
          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 Translation
            response structure.
          readOnly: true
      required:
        - encryptedResponse
        - nonce
      examples:
        - encryptedResponse: >-
            b2c3d4e5f67890abcdef1234567890abcdef12345678901234567890abcdef12345678...
          nonce: e5d4c3b2a19876543210fedcba987654
    rvencAudioTranslationInferenceParams:
      type: object
      description: >-
        Decrypted inference parameters that are encrypted and sent as
        encryptedInference for audio translation. This schema documents the
        structure of the JSON that should be encrypted and included in the
        encryptedInference field. Note: Translation always outputs English text
        regardless of the input language.
      properties:
        model:
          type: string
          description: >-
            ID of the model to use. Only openai/whisper-large-v3 is currently
            available for translations.
          enum:
            - openai/whisper-large-v3
        prompt:
          type: string
          description: >-
            An optional text to guide the model's style or continue a previous
            audio segment. The prompt should be in English to match the output
            language.
        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).
        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.
      required:
        - model
      additionalProperties: false
      examples:
        - model: openai/whisper-large-v3
          response_format: json
        - model: openai/whisper-large-v3
          prompt: This is a technical discussion.
          temperature: 0.3
          response_format: text
        - model: openai/whisper-large-v3
          response_format: verbose_json
    rvencTranslationDecryptedResponse:
      type: object
      description: >-
        Decrypted audio translation result matching OpenAI's Translation
        response. When `encryptedResponse` is decrypted, it will match this
        structure.
      properties:
        text:
          type: string
          description: The translated text (in English).
          examples:
            - Hello world
        task:
          type: string
          description: The task performed, typically 'translate'. (Verbose JSON only)
          examples:
            - translate
        language:
          type: string
          description: The detected language of the input audio. (Verbose JSON only)
          examples:
            - spanish
        duration:
          type: number
          description: The duration of the audio in seconds. (Verbose JSON only)
          examples:
            - 3.1
        segments:
          type: array
          description: >-
            Segments of the translated 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
      required:
        - text
      additionalProperties: false
      examples:
        - text: The quick brown fox jumps over the lazy dog.
        - task: translate
          language: german
          duration: 4.5
          text: I am a Berliner.
          segments:
            - id: 0
              seek: 0
              start: 0
              end: 4.5
              text: I am a Berliner.
              tokens:
                - 50364
                - 314
                - 716
                - 257
                - 45115
                - 13
                - 50589
              temperature: 0
              avg_logprob: -0.15
              compression_ratio: 1.1
              no_speech_prob: 0.05
  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.

````