> ## 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. # Execute Tool > Execute a specific tool by passing encrypted parameters. # 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"; const client = await createRvencClient({ apiKey: process.env.PREM_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.PREM_API_KEY, encryptionKeys, requestTimeoutMs: 60000, // optional maxBufferSize: 20 * 1024 * 1024, // optional }); ``` ```typescript theme={"system"} // Generate an image const image = await client.tools.generateImage({prompt: "sunset over mountains"}); console.log(image.fileName); // "generated_image.png" console.log(image.content); // Uint8Array - save or use directly ``` ## Features * ✅ **File-Producing Tools** - Generate images, audio, and custom files * ✅ **File-Processing Tools** - Extract content from PDFs, images, audio, video, and other file types * ✅ **Simple Tools** - Web search, time, web scraping * ✅ **RAG Tools** - Search indexed documents with an optional file filter * ✅ **End-to-end Encryption** - All tool calls use end-to-end encryption * ✅ **Automatic Decryption** - The SDK automatically downloads and decrypts files * ✅ **TypeScript** - Full type safety ## Tools All tool calls use end-to-end encryption. The SDK automatically downloads and decrypts files. ### File-Producing Tools Generate files with these tools. The SDK automatically decrypts the files and returns them: ```typescript theme={"system"} import fs from "fs"; // Generate an image const image = await client.tools.generateImage({prompt: "sunset over mountains"}); console.log(image.fileName); // "generated_image.png" console.log(image.content); // Uint8Array - save or use directly fs.writeFileSync(image.fileName, image.content); // Generate audio from text const audio = await client.tools.audioGenerateFromText({text: "Hello, world!"}); fs.writeFileSync(audio.fileName, audio.content); // Create a custom file const file = await client.tools.createFileForUser( { fileName: 'test_file', fileExtension: 'txt', fileContent: 'This is the content of the test file.', mimeType: 'text/plain' } ); fs.writeFileSync(file.fileName, file.content); ``` ### File-Processing Tools Process uploaded files and get the results: ```typescript theme={"system"} import fs from "fs"; // Upload a file first const upload = await client.files.upload({ file: new Uint8Array(fs.readFileSync("./image.jpg")), fileName: "image.jpg", }); // Describe and caption image const description = await client.tools.imageDescribeAndCaption({fileId: upload.id}); console.log(description); // Extract PDF content const pdfUpload = await client.files.upload({ file: new Uint8Array(fs.readFileSync("./doc.pdf")), fileName: "doc.pdf", }); const pdfContent = await client.tools.getPDFContent({fileId: pdfUpload.id}); console.log(pdfContent); // Transcribe audio const audioUpload = await client.files.upload({ file: new Uint8Array(fs.readFileSync("./audio.mp3")), fileName: "audio.mp3", }); const transcript = await client.tools.transcribeAudioToText({fileId: audioUpload.id}); console.log(transcript); // Video description const videoUpload = await client.files.upload({ file: new Uint8Array(fs.readFileSync("./video.mp4")), fileName: "video.mp4", }); const videoDesc = await client.tools.videoDescribeAndCaption({fileId: videoUpload.id}); console.log(videoDesc); ``` ### Simple Tools These tools do not process files: ```typescript theme={"system"} // Get current time const time = await client.tools.getTime({timezone: 'America/New_York'}); console.log(time); // Web search const searchResults = await client.tools.webSearchTool({query: 'latest AI news'}); console.log(searchResults); // Web page scraper const pageContent = await client.tools.webPageScraperTool({url: 'https://example.com', renderJs: false}); console.log(pageContent); // RAG search across your uploaded files const ragResults = await client.tools.searchRag({ query: 'test query', }); console.log(ragResults); ``` ## Available Tools ### File-Producing Tools * `generateImage(params: { prompt: string })` - Generate images from text * `audioGenerateFromText(params: { text: string })` - Text-to-speech * `createFileForUser(params: { fileName: string, fileExtension: string, fileContent: string, mimeType: string })` - Create custom files ### File-Processing Tools * `imageDescribeAndCaption(params: { fileId: string })` - Describe images * `imageDescribeAndCaptionFallback(params: { fileId: string })` - Alternative image description * `videoDescribeAndCaption(params: { fileId: string })` - Describe videos * `getPDFContent(params: { fileId: string })` - Extract PDF text * `getTextDocumentContent(params: { fileId: string })` - Extract document text * `transcribeAudioToText(params: { fileId: string, language?: string })` - Audio transcription * `transcribeAudioWithDiarization(params: { fileId: string, language?: string })` - Transcription with speakers * `audioDiarization(params: { fileId: string })` - Identify speakers * `getFileContentOCR(params: { fileId: string })` - OCR on images * `getSpreadsheetContent(params: { fileId: string })` - Extract spreadsheet data * `getDataFileContent(params: { fileId: string })` - Extract data file content * `getPowerPointContent(params: { fileId: string, slideNumbers?: number[] })` - Extract presentation content ### Simple Tools * `getTime(params: { timezone: string })` - Get current time * `webSearchTool(params: { query: string, country?: string, searchLang?: string })` - Web search * `webPageScraperTool(params: { url: string, renderJs?: boolean })` - Scrape web pages ### RAG Tools * `searchRag(params: { query: string })` - Search indexed documents with an optional file filter ## Configuration Options | Option | Type | Default | Description | | ------------------ | ---------------- | -------------- | ------------------------------- | | `apiKey` | `string` | **required** | Authorization token | | `encryptionKeys` | `EncryptionKeys` | auto-generated | Pre-generated ML-KEM keys | | `dekStore` | `DEKStore` | auto-generated | Data encryption keys for files | | `requestTimeoutMs` | `number` | `30000` | Request timeout in milliseconds | | `maxBufferSize` | `number` | `10485760` | Max SSE buffer size (10MB) | ## Security Notes * ⚠️ **Keep your DEK store secure**. The DEK store contains all of your encryption keys. * ⚠️ **Do not commit `dek-store.json`** to version control. * ⚠️ **Use environment variables** for API keys. * ⚠️ **Save the dekStore after each file upload**. The dekStore holds the DEKs for your files. * ⚠️ **Make a backup of your dekStore**. If you lose it, you lose access to your uploaded files. ## TypeScript Types ```typescript theme={"system"} import type { RvencClient, RvencClientOptions, DEKStore, EncryptionKeys, FileUploadOptions, UploadedFile, DecryptedFile, ToolsClient, } from "@premai/api-sdk"; ``` ## OpenAPI ````yaml post /tools/{id} openapi: 3.1.0 info: title: Prem API description: Reference documentation for the Prem API. 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: /tools/{id}: post: tags: - Chats - dev-api summary: Execute Tool description: Execute a specific tool by passing encrypted parameters. operationId: executeTool parameters: - name: id in: path required: true description: >- The tool identifier (e.g., generateImage, audioGenerateFromText, createFileForUser) schema: type: string requestBody: $ref: '#/components/requestBodies/executeToolRequest' responses: '200': $ref: '#/components/responses/executeToolResponse' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' security: - BearerAuth: [] ApiKeyAuth: [] components: requestBodies: executeToolRequest: required: true content: application/json: schema: $ref: '#/components/schemas/executeToolRequest' responses: '400': description: Bad request content: application/json: schema: type: object properties: status: type: integer enum: - 400 - 401 - 403 - 404 - 429 - 502 - 503 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 - 429 - 502 - 503 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 - 429 - 502 - 503 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 '404': description: Resource not found content: application/json: schema: allOf: - type: object properties: status: type: integer enum: - 400 - 401 - 403 - 404 - 429 - 502 - 503 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: - 404 executeToolResponse: description: Tool executed successfully with encrypted response content: application/json: schema: allOf: - $ref: '#/components/schemas/Response200' - type: object properties: data: $ref: '#/components/schemas/executeToolResponse' schemas: executeToolRequest: type: object description: >- Request body for executing a tool with encrypted parameters. The structure varies based on the tool type: simple tools, file output tools, or file input tools. oneOf: - title: Simple Tool Request description: >- Request for simple tools that don't involve file I/O: webSearchTool, getTime, webPageScraperTool type: object properties: cipherText: type: string description: >- Cipher text from ML-KEM encapsulation for shared secret generation encryptedParams: type: string description: Encrypted JSON string containing the tool parameters nonce: type: string description: Nonce used for encrypting the parameters payload required: - cipherText - encryptedParams - nonce additionalProperties: false examples: - title: Web Search Request value: cipherText: a1b2c3d4e5f6... encryptedParams: 9f8e7d6c5b4a... nonce: 1a2b3c4d5e6f... - title: File Output Tool Request description: >- Request for tools that generate files: generateImage, audioGenerateFromText, createFileForUser. Requires additional DEK encryption materials for secure file output. type: object properties: cipherText: type: string description: >- Cipher text from ML-KEM encapsulation for shared secret generation encryptedParams: type: string description: Encrypted JSON string containing the tool parameters nonce: type: string description: Nonce used for encrypting the parameters payload encryptedDEK: type: string description: Encrypted Data Encryption Key (DEK) for file output encryption dekNonce: type: string description: Nonce used for encrypting the DEK wrappedDEK: type: string description: >- Wrapped Data Encryption Key for file storage to enable later file decryption kid: type: string description: >- Key identifier (SHA3-256 hash of the public key used for encryption) for file metadata storage required: - cipherText - encryptedParams - nonce - encryptedDEK - dekNonce - wrappedDEK - kid additionalProperties: false examples: - title: Generate Image Request value: cipherText: a1b2c3d4e5f6... encryptedParams: 9f8e7d6c5b4a... nonce: 1a2b3c4d5e6f... encryptedDEK: 7g8h9i0j1k2l... dekNonce: 3m4n5o6p7q8r... wrappedDEK: 9s0t1u2v3w4x... kid: sha3_256_hash_of_public_key - title: File Input Tool Request description: >- Request for tools that process existing files: imageDescribeAndCaption, imageDescribeAndCaptionFallback, videoDescribeAndCaption, getPDFContent, getTextDocumentContent, transcribeAudioToText, transcribeAudioWithDiarization, audioDiarization, getSpreadsheetContent, getPowerPointContent, getDataFileContent, getFileContentOCR. Requires fileId and DEK for file decryption. type: object properties: cipherText: type: string description: >- Cipher text from ML-KEM encapsulation for shared secret generation nonce: type: string description: Nonce used for encrypting the parameters payload fileId: type: string description: File ID of the encrypted file to process encryptedDEK: type: string description: Encrypted Data Encryption Key (DEK) dekNonce: type: string description: Nonce used for encrypting the DEK encryptedFileDEK: type: string description: Encrypted Data Encryption Key (DEK) for file decryption fileDEKNonce: type: string description: Nonce used for encrypting the DEK required: - cipherText - nonce - fileId - encryptedDEK - dekNonce - encryptedFileDEK - fileDEKNonce additionalProperties: false examples: - title: PDF Content Request value: cipherText: a1b2c3d4e5f6... nonce: 1a2b3c4d5e6f... fileId: file_encrypted_019ae533-a975-7cbb-9147-4d7583a335e3 encryptedDEK: 7g8h9i0j1k2l... dekNonce: 3m4n5o6p7q8r... encryptedFileDEK: 7g8h9i0j1k2l... fileDEKNonce: 3m4n5o6p7q8r... - title: RAG Tool Request description: >- Request for tools that perform RAG operations: searchRag. Requires additional RAG DEK encryption materials for secure search. type: object properties: cipherText: type: string description: >- Cipher text from ML-KEM encapsulation for shared secret generation encryptedParams: type: string description: Encrypted JSON string containing the tool parameters nonce: type: string description: Nonce used for encrypting the parameters payload encryptedDEK: type: string description: Encrypted Data Encryption Key (DEK) for file output encryption dekNonce: type: string description: Nonce used for encrypting the DEK encryptedFileDEKs: type: array description: Encrypted Data Encryption Keys (DEKs) for file decryption items: type: object properties: encryptedDEK: type: string description: Encrypted Data Encryption Key (DEK) nonce: type: string description: Nonce used for encrypting the DEK fileId: type: string description: File ID of the encrypted file to process required: - encryptedDEK - nonce - fileId additionalProperties: false encryptedRagDEK: type: string description: >- Encrypted RAG Data Encryption Key (DEK) for file output encryption ragDEKNonce: type: string description: Nonce used for encrypting the RAG DEK encryptedRagVersion: type: string description: Encrypted RAG Version ragVersionNonce: type: string description: Nonce used for encrypting the RAG Version required: - cipherText - encryptedParams - nonce - encryptedDEK - dekNonce - encryptedFileDEKs - encryptedRagDEK - ragDEKNonce - encryptedRagVersion - ragVersionNonce additionalProperties: false examples: - title: RAG Search Request value: cipherText: a1b2c3d4e5f6... encryptedParams: 9f8e7d6c5b4a... nonce: 1a2b3c4d5e6f... encryptedDEK: 7g8h9i0j1k2l... dekNonce: 3m4n5o6p7q8r... encryptedFileDEKs: - encryptedDEK: 7g8h9i0j1k2l... nonce: 3m4n5o6p7q8r... fileId: file_encrypted_019ae533-a975-7cbb-9147-4d7583a335e3 encryptedRagDEK: 7g8h9i0j1k2l... encryptedRagVersion: 7g8h9i0j1k2l... ragDEKNonce: 3m4n5o6p7q8r... ragVersionNonce: 3m4n5o6p7q8r... 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 executeToolResponse: type: object description: Response from tool execution. Structure varies by tool type. oneOf: - title: File Output Response description: >- Response for file-producing tools (generateImage, audioGenerateFromText, createFileForUser) type: object properties: fileId: type: string description: Unique identifier for the created file fileName: type: string description: Encrypted file name (decrypt using DEK) fileSize: type: integer description: File size in bytes handle: type: string description: Encrypted file handle for local access mimeType: type: string description: Encrypted MIME type (decrypt using DEK) s3Path: type: string description: Storage path for the encrypted file success: type: boolean message: type: string description: Human-readable message about the operation required: - fileId - fileName - fileSize - mimeType - s3Path - success additionalProperties: false examples: - fileId: file_encrypted_gen_019ae533-a975-7cbb-9147-4d7583a335e3 fileName: de0b1a99cc4fcb45c1f236b2bb328015375cbe4f... fileSize: 1057063 handle: 46b6fb708c5deb249130605bb16cfb98... mimeType: 9b7369da092f69c6efbe24d6db6501ef... s3Path: >- agentCreatedFiles/file_encrypted_gen_019ae533-a975-7cbb-9147-4d7583a335e3.enc success: true message: Image generated successfully and made available for download - title: Encrypted Response description: >- Encrypted response for all non-file tools. Decrypt encryptedResponse using DEK and nonce. The _decryptedResponse property shows reference structures for each tool type. type: object properties: encryptedResponse: type: string description: >- Encrypted response data. Decrypt using DEK and nonce to get the actual tool response. nonce: type: string description: Nonce used for encryption _decryptedResponse: description: >- **Reference only** - This shows the possible structures that encryptedResponse should contain when decrypted, depending on the tool type. readOnly: true oneOf: - title: Get Time Decrypted type: object properties: now: type: string format: date-time description: Current timestamp in ISO 8601 format timezone: type: string description: Requested timezone required: - now - timezone additionalProperties: false - title: Web Search Decrypted type: string description: >- Markdown formatted search results with titles, URLs, and descriptions examples: - >- ## 1. [Latest AI News - TechCrunch](https://techcrunch.com/ai) The latest artificial intelligence news and updates... --- ## 2. [AI Breakthroughs - MIT](https://mit.edu/ai) Research breakthroughs in machine learning... --- - title: Web Page Scraper Decrypted type: string description: Web page content converted to markdown examples: - >- # Page Title Main content of the web page converted to markdown format... - title: Image/Video Describe Decrypted type: string description: Text description of the image or video content examples: - >- The image shows a sunset over a calm ocean. The sky is painted in shades of orange, pink, and purple. Palm trees are silhouetted against the colorful sky on the left side of the frame. - title: PDF Content Decrypted type: object properties: chunks: type: array items: type: object properties: pageContent: type: string metadata: type: object description: Array of text chunks extracted from the PDF required: - chunks additionalProperties: false - title: Text Document Content Decrypted type: object properties: content: type: string description: Full text content of the document chunks: type: array items: type: object properties: pageContent: type: string metadata: type: object description: Chunked content for easier processing format: type: string description: File format (txt, md, docx, etc.) wordCount: type: integer description: Approximate word count error: type: string required: - content - format additionalProperties: false - title: Transcribe Audio Decrypted type: object properties: text: type: string description: Full transcribed text segments: type: array items: type: object properties: id: type: integer start: type: number end: type: number text: type: string description: Timed segments of the transcription language: type: string description: Detected or specified language required: - text additionalProperties: false - title: Transcribe with Diarization Decrypted type: object properties: segments: type: array items: type: object properties: speaker: type: string start: type: number end: type: number text: type: string description: Segments with speaker labels and timestamps speakers: type: array items: type: string description: List of identified speakers totalDuration: type: number description: Total audio duration in seconds totalWords: type: integer description: Total word count detectedLanguage: type: string description: Detected language required: - segments - speakers additionalProperties: false - title: OCR Decrypted type: string description: Extracted text from OCR processing examples: - |- INVOICE Date: December 4, 2025 Invoice #: INV-001 Item Qty Price Widget A 10 $99.00 Widget B 5 $149.00 Total: $1,735.00 - title: Spreadsheet Content Decrypted type: object properties: format: type: string enum: - csv - xlsx description: Spreadsheet format data: type: array items: type: array description: 2D array of cell values (for CSV) sheets: type: array items: type: object properties: name: type: string data: type: array preview: type: string description: Array of sheets (for XLSX) preview: type: string description: Human-readable table preview rowCount: type: integer columnCount: type: integer error: type: string required: - format - rowCount - columnCount additionalProperties: false - title: Data File Content Decrypted type: object properties: format: type: string enum: - json - xml description: Data file format content: type: string description: Pretty-printed file content summary: type: object description: Summary of the data structure properties: type: type: string length: type: integer keys: type: array items: type: string keyCount: type: integer rootTag: type: string elementCount: type: integer error: type: string required: - format - content additionalProperties: false - title: PowerPoint Content Decrypted type: object properties: slides: type: array items: type: object properties: slideNumber: type: integer text: type: string notes: type: string hasImages: type: boolean imageCount: type: integer recommendedOcr: type: boolean textLength: type: integer description: Array of slide content totalSlides: type: integer description: Total number of slides format: type: string description: PowerPoint format (pptx, ppt, etc.) formattedContent: type: string description: Human-readable formatted content of all slides ocrSummary: type: object properties: slidesNeedingOcr: type: integer slidesWithImages: type: integer slidesWithMinimalText: type: integer error: type: string required: - slides - totalSlides - format - formattedContent additionalProperties: false - title: Audio Diarization Decrypted type: object properties: speakers: type: array items: type: object properties: speaker: type: string segments: type: array description: Audio separated by speakers required: - speakers additionalProperties: false - title: RAG Search Decrypted type: string description: Search results from user's document store examples: - Relevant document chunks matching the search query... required: - encryptedResponse - nonce additionalProperties: false examples: - encryptedResponse: encrypted_data_here... nonce: nonce_value_here... 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. ````