@parallax-ai/sdk

Official TypeScript SDK for the Parallax AI platform.

• Zero dependencies — uses native fetch
• Works in browsers (cookie-based auth) and Node.js (API key / token auth)
• Full TypeScript types for all requests and responses
• Automatic access token refresh on 401

Installation

npm install @parallax-ai/sdk
# or
yarn add @parallax-ai/sdk

Quick Start

import { ParallaxAI } from '@parallax-ai/sdk';

// Server-side with API key
const client = new ParallaxAI({ apiKey: 'pk_live_...' });

// Browser (uses HTTP-only cookies automatically)
const client = new ParallaxAI({ baseUrl: 'https://api.parallax.kr' });

// Direct access token
const client = new ParallaxAI({ accessToken: 'eyJ...' });

Configuration

const client = new ParallaxAI({
  baseUrl: 'https://api.parallax.kr', // default
  apiKey: 'pk_live_...',                  // server-side
  accessToken: 'eyJ...',                  // direct token
  timeout: 30000,                         // ms, default 30s
  onTokenRefresh: ({ accessToken }) => {
    localStorage.setItem('token', accessToken);
  },
});

Error Handling

import { ParallaxAPIError } from '@parallax-ai/sdk';

try {
  const user = await client.users.me();
} catch (err) {
  if (err instanceof ParallaxAPIError) {
    console.error(err.statusCode); // e.g. 401
    console.error(err.error);      // e.g. "UNAUTHORIZED"
    console.error(err.message);    // human-readable message
  }
}

Module Reference

Auth

// Login
const { accessToken, user } = await client.auth.login({
  email: '[email protected]',
  password: 'secret',
});

// Register
await client.auth.register({ email: '[email protected]', password: 'secret', name: 'Alice' });

// Google / Apple OAuth
await client.auth.google({ idToken: 'google_id_token' });
await client.auth.apple({ identityToken: 'apple_token' });

// Password reset flow
await client.auth.forgotPassword({ email: '[email protected]' });
await client.auth.resetPassword({ token: 'reset_token', newPassword: 'newSecret' });

// Email verification
await client.auth.verifyEmail({ token: 'verify_token' });
await client.auth.resendVerification({ email: '[email protected]' });

// Logout
await client.auth.logout();

Users

// Get current user
const me = await client.users.me();

// Update profile
await client.users.updateMe({ name: 'Alice', language: 'en' });

// Settings
const settings = await client.users.getSettings();
await client.users.updateSettings({ theme: 'dark' });

// Plan & access
await client.users.updatePlan({ plan: 'pro' });
const access = await client.users.planAccess();

// Upload profile image
await client.users.uploadProfileImage(file);

// GDPR data export
const job = await client.users.requestDataExport();
const status = await client.users.getDataExportStatus(job.jobId);
const { url } = await client.users.getDataExportDownload(job.jobId);

// Delete account
await client.users.deleteMe();

Rooms

// List user's rooms — server returns { rooms, total? }
const { rooms, total } = await client.rooms.list();

// Create a room
const room = await client.rooms.create({
  name: 'My Chat',
  modelId: 'gpt-4o',
  systemPrompt: 'You are a helpful assistant.',
});

// Get / update / delete
const room = await client.rooms.get(roomId);
await client.rooms.update(roomId, { name: 'Renamed' });
await client.rooms.delete(roomId);

// Archive operations
await client.rooms.archive(roomId);
await client.rooms.unarchive(roomId);
await client.rooms.archiveAll();
await client.rooms.deleteAll();
await client.rooms.deleteAllArchived();

const archived = await client.rooms.listArchived();

Messages

// Send a message
const message = await client.messages.create({
  roomId: 'room_abc',
  content: 'Hello!',
  modelId: 'gpt-4o',
});

// Get conversation history — server returns { messages, total, hasMore, nextOffset? }
const { messages, total, hasMore } = await client.messages.listByRoom(roomId, { page: 1, limit: 50 });

// Monthly usage
const usage = await client.messages.monthlyUsage();
// { messageCount, tokensUsed, limit, remaining }

// Feedback
await client.messages.submitFeedback(messageId, {
  rating: 'thumbs_up',
  comment: 'Great answer!',
});

Characters

// Browse public characters
const { items } = await client.characters.list({ page: 1, limit: 20 });
const categories = await client.characters.listCategories();
const tags = await client.characters.listTags();

// By category / tag
const byCategory = await client.characters.listByCategory('anime');
const byTag = await client.characters.listByTag('fantasy');

// My characters
const mine = await client.characters.listMy();

// CRUD
const char = await client.characters.create({ name: 'Aria', visibility: 'public' });
await client.characters.update(charId, { description: 'An AI companion' });
await client.characters.delete(charId);

// Images
await client.characters.updateProfileImage(charId, imageFile);
await client.characters.addImage(charId, imageFile, { isLocked: true, unlockTokenCost: 100 });
await client.characters.deleteImage(charId, imageId);

// Report
await client.characters.report(charId, { reason: 'inappropriate', details: '...' });

// Lorebook
const entries = await client.characters.getLorebookEntries(charId);
await client.characters.createLorebookEntry(charId, { key: 'home', value: 'Tokyo' });
await client.characters.updateLorebookEntry(charId, entryId, { value: 'Osaka' });
await client.characters.deleteLorebookEntry(charId, entryId);
await client.characters.bulkUpdateLorebook(charId, { entries: [...] });

Character Chats

// Start / resume a session
const { sessionId, messages } = await client.characterChats.start(characterId);

// Send a message
const { assistantMessage } = await client.characterChats.sendMessage(sessionId, {
  content: 'Hello Aria!',
});

// Session history
const session = await client.characterChats.getSession(sessionId);
const { items } = await client.characterChats.listSessions();

// Unlocked images
const images = await client.characterChats.getUnlockedImages(sessionId);

// End session
await client.characterChats.endSession(sessionId);

Projects

// CRUD
const project = await client.projects.create({ name: 'Research', description: '...' });
const { items } = await client.projects.list();
await client.projects.update(projectId, { name: 'Updated' });
await client.projects.delete(projectId);

// Files
const { items: files } = await client.projects.listFiles(projectId);
const file = await client.projects.uploadFile(projectId, pdfFile);
const { url } = await client.projects.downloadFile(projectId, fileId);
await client.projects.deleteFile(projectId, fileId);

// Vector search (RAG)
const results = await client.projects.search(projectId, {
  query: 'quarterly revenue',
  topK: 5,
});

Storage

// Upload
const { path, url } = await client.storage.upload(file, 'folder/document.pdf');

// List directory
const items = await client.storage.list({ path: 'my-folder' });

// Download
const { url } = await client.storage.download('my-folder/file.pdf');

// File operations
await client.storage.mkdir({ path: 'new-folder' });
await client.storage.move({ sourcePath: 'old/path.jpg', destinationPath: 'new/path.jpg' });
await client.storage.delete({ path: 'to-delete/file.jpg' });

// Quota
const info = await client.storage.info();
const quota = await client.storage.quota();

Payment

// Start checkout
const { url } = await client.payment.createCheckoutSession({
  priceId: 'price_pro_monthly',
  successUrl: 'https://myapp.com/success',
  cancelUrl: 'https://myapp.com/cancel',
});
window.location.href = url;

// Customer portal
const { url } = await client.payment.createPortalSession({
  returnUrl: 'https://myapp.com/billing',
});

// Billing info
const billing = await client.payment.billingSummary();
const { items } = await client.payment.paymentHistory();
const sub = await client.payment.currentSubscription();

// Cancel
await client.payment.cancelSubscription();

Models

// Browse
const { items } = await client.models.list();
const popular = await client.models.popular();
const textModels = await client.models.byCategory('text');

// Search
const { items } = await client.models.search({ q: 'claude', category: 'text' });

// Get details
const model = await client.models.get(modelId);

Video

// Browse public gallery
const { items } = await client.video.list();
const mine = await client.video.listMy();

// Generate
const video = await client.video.create({
  prompt: 'A cat surfing at sunset',
  modelId: 'runway-gen3',
});

// Poll status
const v = await client.video.get(video.id);
// v.status: 'pending' | 'processing' | 'completed' | 'failed'

// Interactions
await client.video.like(video.id);
await client.video.update(video.id, { visibility: 'public' });
await client.video.delete(video.id);

Iris (Visual Automation)

// Workflows
const wf = await client.iris.createWorkflow({ name: 'Image Pipeline' });
const { items } = await client.iris.listWorkflows();
await client.iris.updateWorkflow(wf.id, { status: 'active' });   // PATCH
await client.iris.deleteWorkflow(wf.id);

// Execute (POST /api/iris/workflows/:id/execute)
const exec = await client.iris.executeWorkflow(wf.id, { input: { prompt: '...' } });
const status = await client.iris.getExecutionStatus(exec.executionId);
const nodeResult = await client.iris.getNodeResults(exec.executionId, 'node-1');

// Cancel (POST .../cancel) and retry (POST .../retry) are distinct from delete
await client.iris.cancelExecution(exec.executionId);
await client.iris.retryExecution(exec.executionId);
await client.iris.deleteExecution(exec.executionId);

// Logs
const logs = await client.iris.getExecutionLogs(exec.executionId);

// Assets
const asset = await client.iris.uploadAsset(videoFile);
const { items: assets } = await client.iris.listAssets();
await client.iris.deleteAsset(asset.id);

// Templates & Library
const templates = await client.iris.listTemplates({ category: 'video' });
const library = await client.iris.listLibrary();

// Batch
const batch = await client.iris.createBatch({ workflowId: wf.id, items: [{}, {}, {}] });

// External trigger (POST /api/iris/trigger/:workflowId)
await client.iris.trigger(wf.id, { input: { prompt: 'go' } });

// Media tools
const subtitles = await client.iris.createSubtitles({ assetId: asset.id, language: 'en' });
const faceRestored = await client.iris.restoreFaces(asset.id);
const colorized = await client.iris.colorize(asset.id);
const reframed = await client.iris.autoReframe({ assetId: asset.id, targetAspectRatio: '9:16' });

Notifications

const { notifications, total, hasMore } = await client.notifications.list({ unreadOnly: true });
const { count } = await client.notifications.unreadCount();
await client.notifications.markRead(notifId);
await client.notifications.markAllRead();
await client.notifications.delete(notifId);

API Keys

// Create (key value is returned ONCE)
const { id, key } = await client.apiKeys.create({
  name: 'Production App',
  scopes: ['chat', 'storage'],
  expiresAt: '2027-01-01T00:00:00Z',
});

// Server returns { apiKeys, total }
const { apiKeys, total } = await client.apiKeys.list();
const usage = await client.apiKeys.getUsage(id);

// Rotate
const { key: newKey } = await client.apiKeys.rotate(id);
await client.apiKeys.delete(id);

Webhooks

const wh = await client.webhooks.create({
  url: 'https://myapp.com/hooks',
  events: ['workflow.completed', 'payment.success'],
  secret: 'my_signing_secret',
});

// Server returns { webhooks, total }
const { webhooks } = await client.webhooks.list();
await client.webhooks.update(wh.id, { isActive: false });

// Server returns { logs, total }
const { logs } = await client.webhooks.getLogs(wh.id);
const test = await client.webhooks.test(wh.id);

await client.webhooks.delete(wh.id);

Search

const results = await client.search.global({
  q: 'marketing strategy',
  types: ['rooms', 'characters', 'files'],
  limit: 5,
});

// Each bucket is SearchResultItem[] — { id, name, description?, type }
console.log(results.rooms);
console.log(results.characters);
console.log(results.files);

Favorites

await client.favorites.add({ type: 'character', targetId: 'char_abc' });
await client.favorites.add({ type: 'model', targetId: 'model_xyz' });

const { items } = await client.favorites.list({ type: 'character' });
await client.favorites.remove(favoriteId);

TypeScript Types Reference

All types are exported from the root:

import type {
  // Common
  PaginatedResponse,
  ParallaxAPIError,
  RequestOptions,

  // Auth
  AuthResponse,
  LoginInput,
  RegisterInput,

  // Users
  User,
  UserPlan,
  UserSettings,
  PlanAccess,

  // Rooms
  Room,
  CreateRoomInput,

  // Messages
  Message,
  MonthlyUsage,

  // Characters
  Character,
  LorebookEntry,

  // Character Chats
  CharacterChatSession,

  // Projects
  Project,
  ProjectFile,
  ProjectSearchResult,

  // Storage
  StorageItem,
  StorageQuota,

  // Payment
  CurrentSubscription,
  BillingSummary,

  // Models
  Model,
  ModelCategory,

  // Video
  Video,
  VideoStatus,

  // Iris
  Workflow,
  Execution,
  IrisAsset,

  // Notifications & API keys & webhooks
  Notification,
  NotificationType,
  NotificationsListResponse,
  ApiKey,
  ApiKeysListResponse,
  Webhook,
  WebhooksListResponse,
  WebhookLogsResponse,

  // Search & favorites & prompts
  GlobalSearchResponse,
  SearchResultItem,
  Favorite,
  Prompt,
} from '@parallax-ai/sdk';

License

MIT