Disciplines · Training

Oshun AI Integration Code Examples

Text-to-speech synthesis and voice management:

7sections2 minread
Markdown source
On this page

This directory contains comprehensive, production-ready code examples for the Oshun AI provider integrations. These examples demonstrate best practices for using ElevenLabs, ComfyUI/RunComfy, and Civitai APIs.

Available Examples#

ElevenLabs (elevenlabs-examples.ts)#

Text-to-speech synthesis and voice management:

Section Topics Covered
1. Configuration Basic & advanced initialization
2. Synthesis Basic TTS, voice settings, models, audio tags, long-form
3. Streaming WebSocket sessions, interactive streaming
4. Voice Management List, get, filter, select voices
5. Voice Cloning Instant cloning, quality validation
6. Voice Design Generate custom voices from descriptions
7. Error Handling Error types, retry patterns
8. Monitoring Statistics, health checks
9. Cleanup Proper shutdown, resource management
10. Complete Example Full voice assistant implementation

ComfyUI/RunComfy (comfyui-examples.ts)#

Workflow execution and image generation:

Section Topics Covered
1. Configuration Basic & advanced initialization
2. Workflows txt2img, img2img, LoRA, inpainting, ControlNet
3. Batch Processing Parallel execution, progress tracking, rate limiting
4. Job Management Status, cancellation, history, timeouts
5. Resources Models, custom nodes, credits
6. Validation Workflow validation, cost estimation
7. Error Handling Error types, retry logic
8. Monitoring Analytics, queue status, health checks
9. Advanced Pipelines, A/B testing, seed variations
10. Cleanup Proper shutdown, auto-cleanup factories

Civitai (civitai-examples.ts)#

Model discovery and generation:

Section Topics Covered
1. Configuration Basic & advanced initialization
2. Model Discovery Search, details, hashes, categories, creators, tags
3. Image Generation AIR URNs, LoRA, quality presets, img2img, ControlNet
4. Video Generation Text-to-video, image-to-video
5. LoRA Training Character, style, motion training
6. Job Management Completion, cancellation, history
7. Cost Management Estimates, balance checking
8. Error Handling Error types, retry patterns
9. Monitoring Analytics, rate limits, health checks
10. Advanced Model comparison, batch generation, variations
11. Cleanup Proper shutdown, auto-cleanup factories

Usage#

Import examples in your code:

typescript
// Import specific examples
import {
  example_basic_synthesis,
  example_streaming_session,
} from '@oshun/training/examples/elevenlabs-examples';

// Or import all examples as a collection
import { elevenlabsExamples } from '@oshun/training/examples/elevenlabs-examples';
import { comfyuiExamples } from '@oshun/training/examples/comfyui-examples';
import { civitaiExamples } from '@oshun/training/examples/civitai-examples';

Running Examples#

bash
# Set required environment variables
export ELEVENLABS_API_KEY=your_key
export RUNCOMFY_API_KEY=your_key
export CIVITAI_API_KEY=your_key

# Run with ts-node or in your application
npx ts-node docs/training/examples/elevenlabs-examples.ts

Key Patterns Demonstrated#

1. Provider Initialization#

All providers follow the same initialization pattern:

typescript
// Minimal configuration
const provider = new Provider({
  apiKey: process.env.API_KEY!,
});

// Full configuration
const provider = new Provider({
  apiKey: process.env.API_KEY!,
  timeout: 60000,
  maxRetries: 5,
  // ... other options
});

2. Error Handling#

Consistent error handling across providers:

typescript
try {
  await provider.operation();
} catch (error) {
  if (error instanceof Error) {
    const apiError = error as Error & { code?: string; retryable?: boolean };

    if (apiError.retryable) {
      // Implement retry logic
    }

    switch (apiError.code) {
      case 'RATE_LIMITED':
        // Handle rate limit
        break;
      case 'AUTHENTICATION_FAILED':
        // Handle auth error
        break;
      // ...
    }
  }
}

3. Retry with Exponential Backoff#

typescript
async function retryWithBackoff<T>(
  operation: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  let delay = 1000;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      if (!isRetryable(error) || attempt === maxRetries) throw error;
      await sleep(delay);
      delay = Math.min(delay * 2, 30000);
    }
  }
}

4. Resource Cleanup#

typescript
const provider = new Provider(config);

try {
  // Use provider
  await provider.doWork();
} finally {
  // Always cleanup
  await provider.shutdown();
}

5. Statistics and Monitoring#

typescript
// All providers expose statistics
const stats = provider.getStats();
console.log(`Success rate: ${(stats.successful / stats.total * 100).toFixed(1)}%`);
console.log(`Average latency: ${stats.averageLatencyMs}ms`);

// Health checks
const healthy = await provider.healthCheck();

Best Practices#

  1. Always initialize with proper configuration - Set timeouts, retries, and other options appropriate for your use case.

  2. Handle errors gracefully - Check error codes and implement appropriate retry logic for transient failures.

  3. Monitor usage - Track statistics to understand your usage patterns and optimize costs.

  4. Clean up resources - Always call shutdown() when done to release connections and clear caches.

  5. Use streaming for real-time applications - For low-latency requirements, use streaming APIs where available.

  6. Batch operations when possible - Group multiple operations to reduce API calls and improve efficiency.

  7. Cache appropriately - Use built-in caching features to reduce redundant API calls.

Next Steps#

After reviewing these examples:

  1. Complete the exercises in ../exercises/ to practice these patterns
  2. Attend the workshops in ../workshops/ for guided learning
  3. Watch the video tutorials (scripts in ../videos/) for visual walkthroughs
  4. Build your own project using these patterns as a foundation

Contributing#

When adding new examples:

  1. Follow the existing section organization (numbered sections)
  2. Include comprehensive JSDoc comments
  3. Export examples individually and as a collection
  4. Update this README with new topics covered