KomilionKomilion
SDK Reference

Komilion SDK

Use the OpenAI SDK with Komilion - just change the base URL.

Installation

Komilion is OpenAI SDK compatible - no special SDK needed

npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KOMILION_API_KEY,
  baseURL: "https://www.komilion.com/api",
});

Chat Completions

Standard OpenAI chat completions with intelligent model selection

Basic Usage

const response = await client.chat.completions.create({
  model: "neo-mode/balanced",  // or "neo-mode/frugal", "neo-mode/premium"
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain machine learning" }
  ],
});

console.log(response.choices[0].message.content);
console.log(response.model);  // The actual model used

Streaming

const stream = await client.chat.completions.create({
  model: "neo-mode/balanced",
  messages: [{ role: "user", content: "Write a poem" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

Parameters

ParameterTypeRequiredDescription
modelstring✅Model name or neo-mode policy
messagesarray✅Conversation history
streamboolean❌Enable streaming
temperaturenumber❌0-2, default 1
max_tokensinteger❌Max response length

Model Selection

Use policies or specify models directly

Neo Mode Policies

neo-mode/frugal

Cheapest models, best for high-volume tasks

neo-mode/balanced

Best value, optimal cost/quality (recommended)

neo-mode/premium

Top models for complex reasoning

Specific Models

Or specify any model directly:

// OpenAI
model: "gpt-4o"
model: "gpt-4o-mini"
model: "o1-preview"

// Anthropic
model: "claude-3-opus-20240229"
model: "claude-3-5-sonnet-20240620"

// Google
model: "gemini-1.5-pro"
model: "gemini-1.5-flash"

// And 200+ more via OpenRouter...

Meeting Transcription
NEW

Transcribe long meetings with speaker diarization via the Komilion SDK

Installation

npm install @komilion/sdk

Small File (Direct Upload)

import { KomilionClient } from "@komilion/sdk";

const client = new KomilionClient({
  apiKey: process.env.KOMILION_API_KEY!
});

// Transcribe with speaker diarization
const result = await client.voice.transcribeMeeting(audioFile, {
  language: "en",
  summarize: true,
  format: "json"
});

console.log(`${result.speakerCount} speakers detected`);
console.log(`Duration: ${result.durationFormatted}`);

// Iterate speaker turns
result.utterances.forEach(utt => {
  console.log(`Speaker ${utt.speaker} [${utt.start}s]: ${utt.text}`);
});

// AI-generated summary
console.log(result.summary);

Large File (Pre-signed Upload)

// Step 1: Get pre-signed upload URL (supports up to 500MB)
const { uploadUrl, audioKey } = await client.voice.upload({
  filename: "board-meeting.mp3",
  contentType: "audio/mpeg"
});

// Step 2: Upload directly to cloud storage
await fetch(uploadUrl, {
  method: "PUT",
  body: fileBlob,
  headers: { "Content-Type": "audio/mpeg" }
});

// Step 3: Transcribe from the uploaded key
const result = await client.voice.transcribeMeetingFromKey(audioKey, {
  language: "sv",     // Swedish
  summarize: true
});

From Public URL

const result = await client.voice.transcribeMeetingUrl(
  "https://example.com/recording.mp3",
  { language: "en", summarize: true }
);

Output Formats

json
Full structured response with speakers, words, paragraphs (default)
text
Plain text with speaker labels
srt
SubRip subtitle format with timestamps
vtt
WebVTT subtitle format with timestamps

Response Structure (JSON)

{
  "transcript": "Full text...",
  "speakerCount": 3,
  "duration": 3600,
  "durationFormatted": "1:00:00",
  "confidence": 0.95,
  "utterances": [
    { "speaker": 0, "text": "...", "start": 0.5, "end": 4.2, "confidence": 0.97 }
  ],
  "paragraphs": [
    { "speaker": 0, "text": "...", "sentences": [...] }
  ],
  "words": [
    { "word": "hello", "speaker": 0, "start": 0.5, "end": 0.8, "confidence": 0.99 }
  ],
  "summary": "AI-generated meeting summary...",
  "cost": 0.33,
  "provider": "deepgram"
}

Voice API

Speech-to-text, text-to-speech, and real-time conversations

Real-time Voice

// Get WebSocket config
const res = await fetch("https://www.komilion.com/api/voice/realtime", {
  method: "POST",
  headers: {
    "Authorization": "Bearer ck_your-api-key-here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    policy: "balanced",  // "frugal" | "balanced" | "premium"
    voice: "alloy"       // Voice to use
  })
});

const config = await res.json();

// Connect via WebSocket
const ws = new WebSocket(config.websocket.url);

Voice Policies

PolicyProviderModelCost
premium
OpenAIgpt-realtime~$0.15/min
balanced
OpenAIgpt-realtime-mini~$0.04/min
frugal
Deepgramnova-2~$0.01/min

Error Handling

Common error codes and how to handle them

StatusCodeDescription
401UNAUTHORIZEDInvalid or missing API key
402INSUFFICIENT_BALANCETop up your wallet
403FORBIDDENAPI key disabled
429RATE_LIMITEDToo many requests
503MODEL_UNAVAILABLEModel temporarily down
try {
  const response = await client.chat.completions.create({...});
} catch (error) {
  if (error.status === 402) {
    console.log("Please top up your wallet");
  } else if (error.status === 429) {
    await sleep(1000);  // Wait and retry
  }
}

API Reference

All REST endpoints

Examples

Code samples