@purikura/ai-video-workers

Production-ready Cloudflare Workers for AI video generation backend.

Features

• ⚡ Edge Computing - Deployed globally on Cloudflare's edge network
• 🔄 Queue-Based Processing - Scalable async AI task processing
• 🔌 WebSocket Support - Real-time generation updates via Durable Objects
• 🎯 Multi-Vendor Support - Fal.AI, KIE.AI, Sora, and more
• 💳 Payment Integration - Stripe + PayPro Global support
• 📦 R2 Storage - Cloudflare R2 for generated content storage
• 🔔 Telegram Alerts - Real-time error and system notifications
• 🛡️ Security First - JWT auth, webhook verification, rate limiting

Architecture

┌─────────────────┐
│   Frontend      │
│  (Next.js)      │
└────────┬────────┘
         │ HTTPS
         ▼
┌─────────────────┐
│  API Gateway    │ ← WebSocket connections (Durable Objects)
│  (Port 8787)    │
└────────┬────────┘
         │
         ├─→ Queue: ai-task-queue
         ├─→ Queue: video-task-queue
         ├─→ Queue: email-queue
         └─→ Queue: license-queue

┌─────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│  AI Processor   │   │ Video Processor  │   │  Email Sender    │
│  (Port 8788)    │   │  (Port 8790)     │   │  (Port 8789)     │
└────────┬────────┘   └────────┬─────────┘   └──────────────────┘
         │                     │
         ├─→ KIE.AI           └─→ Fal.AI
         ├─→ Sora
         └─→ ByteDance

         ▼
┌─────────────────┐   ┌──────────────────┐
│   Supabase      │   │  Cloudflare R2   │
│  (Database)     │   │  (Storage)       │
└─────────────────┘   └──────────────────┘

Quick Start

Installation

npm install @purikura/ai-video-workers

Prerequisites

1. Cloudflare Account - Sign up at cloudflare.com
2. Wrangler CLI - npm install -g wrangler
3. Supabase Project - Create at supabase.com
4. AI Provider Keys - Get from kie.ai, fal.ai
5. Stripe Account - Sign up at stripe.com

Setup

# 1. Copy environment template
cp .env.example .env

# 2. Fill in your actual values in .env
# See ENVIRONMENT.md for detailed instructions

# 3. Login to Cloudflare
wrangler login

# 4. Create KV namespaces
wrangler kv:namespace create "JOB_LOOKUP_KV"
wrangler kv:namespace create "MODEL_CACHE_KV"
wrangler kv:namespace create "IDEMPOTENCY_KV"

# 5. Create queues
wrangler queues create ai-task-queue
wrangler queues create paypro-license-queue
wrangler queues create video-task-queue
wrangler queues create email-queue

# 6. Create R2 bucket
wrangler r2 bucket create purikura

# 7. Update wrangler.toml with IDs from steps 4-6

# 8. Set secrets (interactive)
npm run setup

# OR manually:
wrangler secret put SUPABASE_URL
wrangler secret put SUPABASE_ANON_KEY
# ... (see ENVIRONMENT.md for full list)

# 9. Deploy all workers
npm run deploy

Development

# Start all workers locally
npm run dev

# Workers will be available at:
# - API Gateway: http://localhost:8787
# - Processor: http://localhost:8788
# - Email Sender: http://localhost:8789

# Test API endpoint
curl http://localhost:8787/health

Deployment

# Deploy all workers
npm run deploy

# Or deploy individually
npm run deploy:api-gateway
npm run deploy:processor
npm run deploy:email-sender
npm run deploy:video-processor

# View logs
npm run logs

# Tail specific worker
npm run tail
npm run tail:processor
npm run tail:email

API Endpoints

API Gateway (api-gateway)

Health Check

GET /health

Generate Video/Image

POST /api/generate
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "model": "sora-turbo",
  "input": {
    "prompt": "A beautiful sunset over mountains",
    "duration": 5,
    "resolution": "1080p"
  }
}

Cost Preview

POST /api/generations/cost-preview
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "model_id": "sora-turbo",
  "parameters": {
    "duration": 5,
    "resolution": "1080p"
  }
}

Stripe Webhook

POST /api/webhooks/stripe
Stripe-Signature: <signature>

KIE.AI Callback

POST /api/callbacks/kie/:jobId
Content-Type: application/json

WebSocket Connection

GET /ws
Upgrade: websocket

See API Documentation for complete endpoint list.

Environment Variables

Required environment variables:

Core Services

• SUPABASE_URL - Supabase project URL
• SUPABASE_ANON_KEY - Public anon key
• SUPABASE_SERVICE_ROLE_KEY - Service role key
• SUPABASE_JWT_SECRET - JWT signing secret

AI Providers

• KIE_API_KEY / KIE_AI_API_KEY - KIE.AI API key
• FAL_AI_KEY / FAL_KEY - Fal.AI API key (optional)

Payment

• STRIPE_SECRET_KEY - Stripe secret key
• STRIPE_WEBHOOK_SECRET - Stripe webhook secret

Storage

• R2_ACCOUNT_ID - Cloudflare account ID
• R2_ACCESS_KEY_ID - R2 access key
• R2_SECRET_ACCESS_KEY - R2 secret key
• R2_PUBLIC_DOMAIN - Public domain for R2
• R2_PUBLIC_URL - Full public URL

Notifications (Optional)

• TELEGRAM_BOT_TOKEN - Telegram bot token
• TELEGRAM_CHAT_ID - Telegram chat ID

See ENVIRONMENT.md for complete documentation.

Configuration

wrangler.toml Files

• wrangler-api-gateway.toml - API Gateway configuration
• processor.toml - AI Processor configuration
• email-sender.toml - Email Sender configuration
• video-processor.toml - Video Processor configuration

KV Namespaces

• JOB_LOOKUP_KV - Maps job IDs to user IDs for callbacks
• MODEL_CACHE_KV - Caches model configurations
• IDEMPOTENCY_KV - Prevents duplicate AI requests

Queues

• ai-task-queue - AI generation tasks (multi-vendor)
• video-task-queue - Video-specific tasks (Fal.AI)
• email-queue - Email sending tasks
• paypro-license-queue - PayPro license processing

R2 Buckets

• purikura - Stores generated videos/images

Durable Objects

• UserSessionManager - WebSocket session management

Architecture Details

API Gateway

• Main entry point for all API requests
• Handles authentication (JWT)
• Routes requests to appropriate handlers
• Manages WebSocket connections via Durable Objects
• Enqueues AI tasks to workers

AI Processor

• Consumes ai-task-queue
• Dispatches to vendor-specific adapters
• Handles vendor callbacks
• Updates job status in database
• Sends WebSocket notifications

Video Processor

• Consumes video-task-queue
• Specialized for Fal.AI video models
• Handles polling for job completion
• Uploads results to R2

Email Sender

• Consumes email-queue
• Sends transactional emails
• Uses Zoho Mail API

Security

Authentication

• JWT tokens signed with SUPABASE_JWT_SECRET
• Verified on every API request
• Row-level security in Supabase

Webhook Verification

• Stripe: Signature verification with STRIPE_WEBHOOK_SECRET
• Vendor callbacks: WEBHOOK_SECRET validation

Rate Limiting

• Per-user rate limits via KV
• Queue-based backpressure
• DLQ for failed tasks

Monitoring

Logs

# Stream live logs
npm run logs

# Tail specific worker
wrangler tail api-gateway
wrangler tail ai-processor

Telegram Alerts

Automatic alerts for:

• Model pricing errors
• Queue failures
• Critical system errors
• Zombie task detection

Setup: Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID

Metrics

View in Cloudflare Dashboard:

• Request count
• Error rate
• Queue depth
• Worker CPU time
• R2 storage usage

Troubleshooting

Common Issues

1. "Required secret not found"

# Set missing secret
wrangler secret put SECRET_NAME

2. "KV namespace not found"

# Create KV namespace
wrangler kv:namespace create "NAMESPACE_NAME"

# Update ID in wrangler.toml

3. "Queue not found"

# Create queue
wrangler queues create queue-name

4. "R2 Access Denied"

• Check R2 API token permissions
• Verify bucket name matches
• Ensure CORS configured

5. "Webhook signature mismatch"

• Get fresh webhook secret from Stripe
• Update: wrangler secret put STRIPE_WEBHOOK_SECRET

Debug Mode

# Enable debug logs
wrangler dev --log-level debug

# View detailed error traces
wrangler tail --format pretty

Production Checklist

Before Deployment

• [ ] All secrets configured via wrangler secret put
• [ ] KV namespaces created and IDs updated
• [ ] Queues created
• [ ] R2 bucket created with public access
• [ ] Supabase tables and RLS policies set up
• [ ] Stripe webhook endpoint configured
• [ ] Telegram alerts set up (recommended)
• [ ] Test in staging environment

After Deployment

• [ ] Verify health endpoint: https://your-worker.workers.dev/health
• [ ] Test video generation end-to-end
• [ ] Monitor logs for errors
• [ ] Check queue depths
• [ ] Verify WebSocket connections
• [ ] Test payment flow
• [ ] Confirm Telegram alerts working

Performance

Benchmarks

• API Gateway: < 50ms p50, < 200ms p99
• Queue Processing: ~500 tasks/second per worker
• WebSocket: < 100ms message latency
• R2 Upload: ~1-2 seconds for 10MB video

Optimization Tips

• Enable caching in MODEL_CACHE_KV
• Use queue batching for bulk operations
• Configure appropriate R2 lifecycle policies
• Monitor and scale workers based on queue depth

Cost Estimation

Cloudflare Workers

• Free Tier: 100,000 requests/day
• Paid: $5/month + $0.50/million requests

Durable Objects

• Free Tier: Included
• Paid: $0.15/million requests

R2 Storage

• Free Tier: 10 GB storage
• Paid: $0.015/GB/month

Queues

• Free Tier: Included
• Paid: Minimal cost for most use cases

Typical Monthly Cost: $10-50 for small to medium traffic

Related Packages

• @purikura/ai-video - Core backend SDK
• @purikura/ai-video-react - React frontend hooks/components

Support

• 📖 Full Documentation
• 🐛 Report Issues
• 💬 Discussions

License

MIT

Changelog

See CHANGELOG.md