Skip to main content
POST
/
tools
/
{id}
Execute Tool
curl --request POST \
  --url https://proxy.cci.prem.io/tools/{id} \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Web Search Request",
  "value": {
    "cipherText": "a1b2c3d4e5f6...",
    "encryptedParams": "9f8e7d6c5b4a...",
    "nonce": "1a2b3c4d5e6f..."
  }
}
'
{
  "status": 200,
  "data": {
    "id": "123"
  },
  "error": null,
  "log": null,
  "validator": null,
  "support_id": null,
  "message": "Resource created successfully",
  "env": "development"
}

TypeScript SDK

The SDK is available on GitHub: premAI-io/pcci-sdk-ts

Usage

Basic Setup

Create a client with auto-generated encryption keys:
import createRvencClient from "./index";

const client = await createRvencClient({
  apiKey: "your-api-key",
});

Pre-generate Keys

You can pre-generate encryption keys and reuse them:
import createRvencClient, { generateEncryptionKeys } from "./index";

const encryptionKeys = await generateEncryptionKeys();

const client = await createRvencClient({
  apiKey: "your-api-key",
  encryptionKeys,
  requestTimeoutMs: 60000,  // optional
  maxBufferSize: 20 * 1024 * 1024, // optional
});
// 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 more
  • Simple Tools - Web search, time, web scraping
  • RAG Tools - Search indexed documents with optional file filtering
  • End-to-end Encryption - All tools are encrypted end-to-end
  • Automatic Decryption - Files are automatically downloaded and decrypted
  • TypeScript - Full type safety

Tools

All tools are encrypted end-to-end. Files are automatically downloaded and decrypted.

File-Producing Tools

Generate files that are automatically decrypted and returned:
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 results:
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

Tools that don’t require file handling:
// 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 optional file filtering

Configuration Options

OptionTypeDefaultDescription
apiKeystringrequiredAuthorization token
encryptionKeysEncryptionKeysauto-generatedPre-generated ML-KEM keys
dekStoreDEKStoreauto-generatedData encryption keys for files
requestTimeoutMsnumber30000Request timeout in milliseconds
maxBufferSizenumber10485760Max SSE buffer size (10MB)

Security Notes

  • ⚠️ Keep your DEK store secure - it contains all encryption keys
  • ⚠️ Never commit dek-store.json to version control
  • ⚠️ Use environment variables for API keys
  • ⚠️ Always persist dekStore after file uploads - file DEKs must be saved
  • ⚠️ Backup your dekStore - losing it means losing access to uploaded files

TypeScript Types

import type {
  RvencClient,
  RvencClientOptions,
  DEKStore,
  EncryptionKeys,
  FileUploadOptions,
  UploadedFile,
  DecryptedFile,
  ToolsClient,
} from "./index";

Authorizations

Authorization
string
header
required

Send your access token as header Authorization: Bearer {accessToken}

Authorization
string
header
required

Your API key that starts with sk_live or sk_test. You can create yours at go.prem.io/api-keys.

Path Parameters

id
string
required

The tool identifier (e.g., generateImage, audioGenerateFromText, createFileForUser)

Body

application/json

Request for simple tools that don't involve file I/O: webSearchTool, getTime, webPageScraperTool

cipherText
string
required

Cipher text from ML-KEM encapsulation for shared secret generation

encryptedParams
string
required

Encrypted JSON string containing the tool parameters

nonce
string
required

Nonce used for encrypting the parameters payload

Response

Tool executed successfully with encrypted response

status
enum<integer>
required

Status code of the response

Available options:
200,
201,
202
data
File Output Response · object
required

Response for file-producing tools (generateImage, audioGenerateFromText, createFileForUser)

Example:
{
"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"
}
message
string | null
required

Message of the response, human readable

Example:

"Resource created successfully"

env
enum<string>
required

API environment

Available options:
development,
production
error
string | null

Error message of the response, human readable

Example:

"Invalid email address"

log

Useful informaiton, not always present, to debug the response

Examples:
{ "request_id": "req_1234567890" }

"Some pertinent log message"

validator

Validator response object, each key is the field name and value is the error message

Example:
{
"email": "Invalid email address",
"password": "Password is required"
}
support_id
string<uuid> | null

Support ID linked to the response, used to identify it when talking with our team

Example:

"support_uuidv7-something-else"