AKI.IO TypeScript/Node.js SDK

A modern TypeScript/Node.js SDK for the AKI.IO AI Model Hub API.

Installation

npm install @aki-io/aki-io

yarn add @aki-io/aki-io

pnpm add @aki-io/aki-io

Quick Start

import { AkiClient } from '@aki-io/aki-io'

const client = new AkiClient({
  endpointName: 'llama3_chat',
  apiKey: 'your-api-key-here'
})

const result = await client.doApiRequest({
  prompt_input: 'Hello, how are you?'
})

console.log(result.text)

Configuration

const client = new AkiClient({
  endpointName: 'llama3_chat',        // Required: API endpoint name
  apiKey: 'your-api-key-here',        // Required: Your API key
  apiServer: 'https://aki.io',        // Optional: API server URL (default: 'https://aki.io')
  outputBinaryFormat: 'base64',       // Optional: 'base64' or 'byteString' (default: 'base64')
  raiseExceptions: false,             // Optional: Throw exceptions on errors (default: false)
  progressInterval: 0.2,              // Optional: Progress poll interval in seconds (default: 0.2)
  returnToolCallDict: false           // Optional: Parse tool calls as JSON (default: false)
})

Usage

Simple Request

import { AkiClient } from '@aki-io/aki-io'

const client = new AkiClient({
  endpointName: 'llama3_chat',
  apiKey: process.env.AKI_API_KEY!
})

const result = await client.doApiRequest({
  prompt_input: 'What is the capital of France?'
})

if (result.success) {
  console.log(result.text)
} else {
  console.error('Error:', result.error)
}

Chat Context

const result = await client.doApiRequest({
  chat_context: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is 2+2?' },
    { role: 'assistant', content: '2+2 equals 4.' },
    { role: 'user', content: 'And what is 3+3?' }
  ]
})

console.log(result.text)

Progress Callbacks

const result = await client.doApiRequest(
  {
    prompt_input: 'Write a long story about a robot.'
  },
  (progressInfo, progressData) => {
    console.log(`Progress: ${progressInfo.progress}%`)
    console.log(`Queue Position: ${progressInfo.queue_position}`)
    
    if (progressData?.text) {
      console.log('Partial text:', progressData.text)
    }
  }
)

console.log('Final result:', result.text)

Async Generator (Streaming)

for await (const update of client.getApiRequestGenerator({ 
  prompt_input: 'Tell me a joke' 
})) {
  if (update.job_state === 'started') {
    console.log('Job started:', update.job_id)
  } else if (update.job_state === 'processing') {
    console.log('Progress:', update.progress_data?.text)
  } else if (update.job_state === 'done') {
    console.log('Final result:', update.result_data?.text)
  }
}

Convenience Function

import { doAkiRequest } from '@aki-io/aki-io'

const result = await doAkiRequest(
  'llama3_chat',
  'your-api-key',
  { prompt_input: 'Hello!' }
)

console.log(result.text)

Validate API Key

const validation = await client.initApiKey()

if (validation.success) {
  console.log('API key is valid')
} else {
  console.error('Invalid API key:', validation.error)
}

Get Available Endpoints

const endpoints = await client.getEndpointList()

console.log('Available endpoints:', endpoints)

Get Endpoint Details

const details = await client.getEndpointDetails('llama3_chat')

console.log('Endpoint details:', details)

Binary Data Handling

import { encodeBinary, decodeBinary } from '@aki-io/aki-io'

const imageBuffer = await fs.readFile('image.png')

const encoded = encodeBinary(imageBuffer, 'png')
console.log(encoded)
// data:image/png;base64,iVBORw0KGgo...

const [format, decoded] = decodeBinary(encoded)
console.log(format)  // 'png'
console.log(decoded) // Buffer containing the image data

Error Handling

import { AkiClient, AkiError, ConnectionError, ValidationError } from '@aki-io/aki-io'

const client = new AkiClient({
  endpointName: 'llama3_chat',
  apiKey: 'your-api-key',
  raiseExceptions: true
})

try {
  const result = await client.doApiRequest({ prompt_input: 'Hello' })
  console.log(result.text)
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid request:', error.message)
  } else if (error instanceof ConnectionError) {
    console.error('Connection failed:', error.message)
  } else if (error instanceof AkiError) {
    console.error('API error:', error.message)
  }
}

API Reference

AkiClient

Constructor

new AkiClient(config: AkiClientConfig)

Methods

• doApiRequest(params, progressCallback?) - Make an API request
• getApiRequestGenerator(params) - Get async generator for streaming
• initApiKey(apiKey?) - Validate API key
• getEndpointList() - Get list of available endpoints
• getEndpointDetails(endpointName?) - Get endpoint details
• cancelRequest(jobId?) - Cancel a running request
• setApiKey(apiKey) - Set new API key
• getVersion() - Get SDK version (static)

Utility Functions

• encodeBinary(data, format?, type?) - Encode binary data to base64
• decodeBinary(base64String) - Decode base64 to binary
• isValidBase64(string) - Check if string is valid base64
• isValidJson(string) - Check if string is valid JSON

Types

interface AkiClientConfig {
  endpointName: string
  apiKey: string
  apiServer?: string
  outputBinaryFormat?: 'base64' | 'byteString'
  raiseExceptions?: boolean
  progressInterval?: number
  returnToolCallDict?: boolean
}

interface ApiResponse {
  success: boolean
  job_id?: string
  text?: string
  images?: string | string[]
  error?: string
  error_code?: number
  // ... additional fields
}

interface ProgressInfo {
  job_id: string
  progress: number
  queue_position: number
  estimate: number
  job_state?: JobState
  success?: boolean
}

interface ProgressData {
  text?: string
  images?: string | string[]
  num_generated_tokens?: number
  // ... additional fields
}

type ProgressCallback = (progressInfo: ProgressInfo, progressData: ProgressData | null) => void
type JobState = 'started' | 'processing' | 'done' | 'canceled' | 'lapsed'

Requirements

• Node.js 18.0.0 or higher
• TypeScript 5.0 or higher (for development)

License

MIT License - see LICENSE file for details.

Support

• Documentation: https://aki.io/docs
• Issues: https://github.com/aki-io-labs/aki-io/issues
• Website: https://aki.io