CelebAI TypeScript SDK

A comprehensive TypeScript SDK for the CelebAI video generation API. This SDK provides easy-to-use methods for authentication, character management, audio/video generation, and webhook handling.

Installation

npm install celebai-ts-sdk

Quick Start

import { CelebAISDK } from 'celebai-ts-sdk';

// Initialize the SDK
const sdk = new CelebAISDK({
  baseURL: 'https://api.celebai.com',
  apiKey: 'your-api-key' // Optional for public endpoints
});

// Example: Get all characters
const charactersResponse = await sdk.characters.getAllCharacters();
if (charactersResponse.data) {
  console.log('Available characters:', charactersResponse.data.characters);
}

// Example: Generate audio
const audioResponse = await sdk.generation.generateAudio({
  character: 'character-uuid',
  prompt: 'Hello, this is a test message!'
});

if (audioResponse.data) {
  console.log('Audio generated:', audioResponse.data.s3_url);
}

SDK Structure

The SDK is organized into the following modules:

🔐 Authentication (sdk.auth)

Handle user authentication and account management.

// Login
const loginResult = await sdk.auth.login({
  email: '[email protected]',
  password: 'password123'
});

// Register
const registerResult = await sdk.auth.register({
  email: '[email protected]',
  password: 'password123'
});

// Get current user
const userResult = await sdk.auth.getCurrentUser();

// Logout
const logoutResult = await sdk.auth.logout();

// Password reset flow
const forgotResult = await sdk.auth.forgotPassword({
  email: '[email protected]'
});

const resetResult = await sdk.auth.resetPassword({
  token: 'reset-token',
  new_password: 'newpassword123'
});

// Email verification
const verifyResult = await sdk.auth.verifyEmail('verification-token');

// Google OAuth
const googleAuthUrl = sdk.auth.googleAuth(); // Returns OAuth URL

👥 Characters (sdk.characters)

Manage celebrities and their video clips.

// Get all available characters
const charactersResult = await sdk.characters.getAllCharacters();

// Get clips for a specific character
const clipsResult = await sdk.characters.getClipsForCharacter('character-uuid');

🎬 Generation (sdk.generation)

Generate audio and video content.

// Generate audio clip
const audioResult = await sdk.generation.generateAudio({
  character: 'character-uuid',
  prompt: 'Your text here'
});

// Generate video with lip sync
const videoResult = await sdk.generation.generateVideo({
  clip: 'video-clip-uuid',
  audio_clip: 'audio-clip-uuid'
});

// Check video generation status
const statusResult = await sdk.generation.getVideoGeneration('generation-uuid');

🔗 Webhooks (sdk.webhook)

Handle webhook notifications from external services.

// Handle LatentSync webhook (typically used server-side)
const webhookResult = await sdk.webhook.handleLatentSyncWebhook({
  id: 'prediction-id',
  status: 'succeeded',
  output: 'https://output-url.com/video.mp4',
  error: null
});

API Response Format

All SDK methods return a consistent response format:

interface ApiResponse<T> {
  data?: T;           // Successful response data
  error?: ApiError;   // Error information
}

interface ApiError {
  message: string;    // Error description
  status: number;     // HTTP status code
}

Error Handling

const result = await sdk.characters.getAllCharacters();

if (result.error) {
  console.error('Error:', result.error.message);
  console.error('Status:', result.error.status);
} else {
  console.log('Success:', result.data);
}

Type Definitions

The SDK includes comprehensive TypeScript types for all API entities:

import {
  User,
  Character,
  Clip,
  AudioClip,
  Generation,
  AudioGenerationRequest,
  VideoGenerationRequest,
  // ... and more
} from 'celebai-ts-sdk';

Configuration Options

const sdk = new CelebAISDK({
  baseURL: 'https://api.celebai.com',  // Required: API base URL
  apiKey: 'your-api-key'               // Optional: API key for authenticated requests
});

Development

Building

npm run build

Testing

npm test

Generating Types

The SDK types are automatically generated from the OpenAPI specification:

npm run generate-types

Examples

Complete Workflow Example

import { CelebAISDK } from 'celebai-ts-sdk';

async function generateVideoExample() {
  const sdk = new CelebAISDK({
    baseURL: 'https://api.celebai.com',
    apiKey: 'your-api-key'
  });

  try {
    // 1. Get available characters
    const charactersResult = await sdk.characters.getAllCharacters();
    if (charactersResult.error) throw new Error(charactersResult.error.message);
    
    const character = charactersResult.data.characters[0];
    console.log('Using character:', character.name);

    // 2. Get clips for the character
    const clipsResult = await sdk.characters.getClipsForCharacter(character.id);
    if (clipsResult.error) throw new Error(clipsResult.error.message);
    
    const clip = clipsResult.data.clips[0];
    console.log('Using clip:', clip.s3_key);

    // 3. Generate audio
    const audioResult = await sdk.generation.generateAudio({
      character: character.id,
      prompt: 'Hello everyone! This is an AI-generated voice.'
    });
    if (audioResult.error) throw new Error(audioResult.error.message);
    
    console.log('Audio generated:', audioResult.data.s3_url);

    // 4. Generate video with lip sync
    const videoResult = await sdk.generation.generateVideo({
      clip: clip.id,
      audio_clip: audioResult.data.audio_clip.id
    });
    if (videoResult.error) throw new Error(videoResult.error.message);
    
    console.log('Video generation started:', videoResult.data.id);

    // 5. Check generation status (poll until complete)
    let completed = false;
    while (!completed) {
      await new Promise(resolve => setTimeout(resolve, 5000)); // Wait 5 seconds
      
      const statusResult = await sdk.generation.getVideoGeneration(videoResult.data.id);
      if (statusResult.error) throw new Error(statusResult.error.message);
      
      const status = statusResult.data.generation.status;
      console.log('Generation status:', status);
      
      if (status === 'completed') {
        console.log('Video URL:', statusResult.data.video_url);
        completed = true;
      } else if (status === 'failed') {
        throw new Error('Video generation failed: ' + statusResult.data.generation.error);
      }
    }

  } catch (error) {
    console.error('Error in video generation workflow:', error);
  }
}

generateVideoExample();

License

MIT

Support

For issues and questions, please visit our GitHub repository or contact our support team.