Disciplines · Integrations

Civitai Integration Documentation

Civitai is a platform for sharing and using AI-generated content, models, and training services.

14sections3 minread
Markdown source
On this page

This directory contains comprehensive documentation for integrating Civitai AI generation capabilities into the Oshun platform.

Document Description
API Documentation Generation API, AIR URNs, image/video generation
Model Management Model discovery, downloads, versioning
Training Guide LoRA training for images and video
Best Practices Optimization, cost management, production tips

Overview#

Civitai is a platform for sharing and using AI-generated content, models, and training services. Oshun integrates with Civitai for:

  • Image Generation: Text-to-image with SD1.5, SDXL, Flux, and Pony models
  • Video Generation: 10 video models including Vidu, Veo3, Hunyuan, and Wan
  • Model Discovery: Search and browse the Civitai model library
  • LoRA Training: Train custom LoRAs for image and video generation
  • Model Management: Download queue, caching, and hot-swap capabilities

Key Features#

  • AIR URN System: Standardized model references across ecosystems
  • Multi-Model Support: SD1.5, SDXL, Flux, Pony, video models
  • Quality Presets: Fast, balanced, quality, highQuality configurations
  • Training Pipelines: Character, style, object, and motion LoRAs
  • Production Ready: Rate limiting, circuit breaker, caching, monitoring

Architecture#

text
┌─────────────────────────────────────────────────────────────────────────────┐
│                        Oshun Civitai Integration                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Application Layer                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Lilith AI Service  │  Isis Factory    │    Yemaya Creative         │   │
│  │  - Avatar gen       │  - Batch gen     │    - Asset creation        │   │
│  │  - Character LoRAs  │  - Upscaling     │    - Style transfer        │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                      │
│  Provider Layer                      ▼                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                     Civitai Provider                                 │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │   │
│  │  │ Generation   │  │ Training     │  │ Model        │              │   │
│  │  │ Provider     │  │ Provider     │  │ Discovery    │              │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘              │   │
│  │                                                                      │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │   │
│  │  │ Rate Limiter │  │ Circuit      │  │ Request      │              │   │
│  │  │              │  │ Breaker      │  │ Cache        │              │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘              │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                      │
│  API Layer                           ▼                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  Civitai API                                                         │   │
│  │  - /v1/images/generate      - Image generation                       │   │
│  │  - /v1/videos/generate      - Video generation                       │   │
│  │  - /v1/models               - Model discovery                        │   │
│  │  - /v1/training             - LoRA training                          │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Getting Started#

Prerequisites#

  1. Civitai API key
  2. Sufficient Buzz balance for generation/training
  3. Node.js 18+ environment

Quick Start#

typescript
import { createCivitaiProvider } from '@oshun/civitai-provider';

// Initialize provider
const provider = createCivitaiProvider(process.env.CIVITAI_API_KEY);

// Generate an image
const job = await provider.generateImage({
  model: 'urn:air:sdxl:checkpoint:civitai:133005@348913',
  params: {
    prompt: 'A majestic dragon flying over a castle at sunset',
    negativePrompt: 'blurry, low quality',
    width: 1024,
    height: 1024,
    steps: 25,
    cfgScale: 7,
  },
});

// Wait for result
const result = await provider.waitForJob(job.jobId);
console.log('Generated image:', result.result?.blobUrl);

Using Quality Presets#

typescript
// Fast preview (12 steps)
const preview = await provider.generateImageWithPreset(
  'urn:air:sdxl:checkpoint:civitai:133005@348913',
  'A beautiful landscape',
  'fast'
);

// High quality (50 steps)
const final = await provider.generateImageWithPreset(
  'urn:air:sdxl:checkpoint:civitai:133005@348913',
  'A beautiful landscape',
  'highQuality'
);

Supported Generation Types#

Type Description Typical Latency Cost
Image (SD1.5) 512x512 generation 5-15s 2 Buzz
Image (SDXL) 1024x1024 generation 15-30s 5 Buzz
Image (Flux) Highest quality 20-45s 8 Buzz
Video 2-10 second clips 30-120s 8-25 Buzz/s
Training LoRA fine-tuning 30min-2hr 50-350 Buzz/1k steps

Supported Models#

Image Generation#

Ecosystem Example Models VRAM Resolution
SD 1.5 Realistic Vision, DreamShaper 4GB 512x512
SDXL Juggernaut XL, RealVisXL 8GB 1024x1024
Flux Flux.1 Dev 24GB Variable
Pony Pony Diffusion V6 8GB 1024x1024

Video Generation#

Model Max Duration LoRA Support Image-to-Video
Vidu Q1 8s No Yes
Veo3 10s No Yes
Hunyuan 8s Yes Yes
Wan 2.1/2.2 8s Yes Yes
Mochi 5s No No

Cost Reference#

Image Generation#

Ecosystem Base Cost With 2 LoRAs
SD 1.5 2 Buzz ~3 Buzz
SDXL 5 Buzz ~6 Buzz
SDXL Draft 3 Buzz ~4 Buzz
Flux 8 Buzz ~9 Buzz

Video Generation (per second)#

Model Draft Standard Professional
LTXV/Mochi 4 8 12
Wan 2.1 5 10 15
Hunyuan 5 10 15
Veo3 12.5 25 37.5

Training (per 1000 steps)#

Base Model Cost
SD 1.5/2.1 50 Buzz
SDXL 100 Buzz
Flux 150-200 Buzz
Video 300-350 Buzz

Provider Comparison#

When to Use Civitai#

Best for:

  • Access to large model library
  • LoRA training capabilities
  • Community models and styles
  • Video generation with LoRAs

Consider alternatives for:

  • Lowest latency requirements (use RunComfy/RunPod)
  • Self-hosted requirements (use ComfyUI directly)
  • Enterprise SLA requirements

Resilience Features#

Rate Limiting#

  • Sliding window algorithm (60 requests/minute)
  • Automatic retry with exponential backoff
  • Pre-request rate limit checking

Circuit Breaker#

  • Opens after 5 failures in 60 seconds
  • Half-open state after 30 second timeout
  • Closes after 3 consecutive successes

Caching#

  • In-memory LRU cache
  • 5 minute default TTL
  • ETag support for conditional requests

Monitoring#

Key Metrics#

  • Success Rate: Target >99%
  • Average Latency: Target <30s for images
  • Cache Hit Rate: Target >50%
  • Buzz Efficiency: Track cost per successful generation

Health Checks#

typescript
const health = await checkHealth();

console.log('Healthy:', health.healthy);
console.log('Rate limit remaining:', health.checks.rateLimit.remaining);
console.log('Circuit state:', health.checks.circuitBreaker.state);
console.log('Cache hit rate:', health.checks.cache.hitRate);

Best Practices Summary#

  1. Use quality presets for consistent results
  2. Cache model metadata to reduce API calls
  3. Monitor Buzz spending with daily budgets
  4. Start with fast presets for iteration
  5. Track seeds for reproducibility
  6. Validate datasets before training
  7. Use appropriate models for the task

Error Handling#

typescript
try {
  const result = await provider.generateImageAndWait(request);
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    // Retry after delay
  } else if (error.code === 'INSUFFICIENT_BUZZ') {
    // Top up account
  } else if (error.code === 'MODEL_NOT_FOUND') {
    // Use fallback model
  }
}

Support#

  • Internal: #ai-generation Slack channel
  • Civitai: Discord
  • API Issues: support@civitai.com