A library and CLI for generating and stitching together AI videos
npm install @hyperplex/hyperflix

Generate and stitch together AI videos with ease
HyperFlix is a powerful library and CLI for generating and stitching together AI videos using LumaAI. It provides:
- Chainable API for elegant workflows
- CLI commands for project management
- Type-safe with TypeScript
- Flexible storage with support for Vercel Blob, AWS S3, and Cloudflare R2
``bashInstall as a package
npm install @hyperplex/hyperflix
🧩 Library Usage
`typescript
import { VideoStitcher } from '@hyperplex/hyperflix';// Create a video stitcher
const stitcher = new VideoStitcher({
title: 'my-awesome-video',
model: 'luma:ray-2', // LumaAI model
aspectRatio: '16:9', // Aspect ratio
videoLength: '5s', // Video duration
defaultPrompt: 'Beautiful landscape' // Default prompt
});
// Initialize with first image (Buffer or URL)
await stitcher.initialize(imageUrlOrBuffer);
// Add keyframes with camera motions (chainable API)
const result = await stitcher.addKeyframe(
secondImageUrlOrBuffer,
'mountain vista', // Prompt
'zoom-in' // Camera motion
);
// Continue adding keyframes
const finalResult = await result.stitcher.addKeyframe(
thirdImageUrlOrBuffer,
'flowing river',
'pan-right'
);
console.log(
Video metadata: ${finalResult.videoUrl});
`$3
`typescript
// Batch generate a video from multiple images
const images = [image1, image2, image3];
const prompts = ['forest', 'mountain', 'river'];
const cameras = ['tilt-up', 'pan-right', 'zoom-out'];const result = await stitcher.generateFrom(images, prompts, cameras);
console.log(
Video URL: ${result.videoUrl});
`💻 CLI Usage
HyperFlix includes a robust command-line interface:
`bash
List all projects
hyperflix listCreate a new project interactively
hyperflix create my-video-projectView project details
hyperflix project details my-video-projectResume editing a project
hyperflix project resume my-video-project
`$3
`bash
hyperflix create my-video-project \
--prompt "A beautiful landscape" \
--model luma:ray-2 \
--aspect 16:9 \
--duration 5s
`🔧 Configuration
Create a
.env file in your project directory:`
Required for API access
LUMAAI_API_KEY=your_lumaai_api_key_hereStorage options (choose one based on your CDN)
VERCEL_BLOB_READ_WRITE_TOKEN=your_vercel_blob_token_hereFor S3 storage:
S3_ACCESS_KEY=your_s3_access_key
S3_SECRET_KEY=your_s3_secret_key
S3_BUCKET=your_s3_bucket
S3_REGION=us-east-1
S3_ENDPOINT=https://s3.amazonaws.com (optional, for custom endpoints)
For Cloudflare R2 storage:
R2_ACCOUNT_ID=your_cloudflare_account_id
R2_ACCESS_KEY_ID=your_r2_access_key
R2_SECRET_ACCESS_KEY=your_r2_secret_key
R2_BUCKET=your_r2_bucket
R2_PUBLIC_URL=https://your-custom-domain.com (optional, for public URLs)
`💾 Storage Providers
HyperFlix supports multiple storage providers for storing your project data:
$3
`typescript
import { VercelBlobCDN } from '@hyperplex/hyperflix';// Create storage service with Vercel Blob
const storage = new VercelBlobCDN('your_token');
// Or use environment variable: VERCEL_BLOB_READ_WRITE_TOKEN
const storage = new VercelBlobCDN();
`$3
`typescript
import { S3CDN } from '@hyperplex/hyperflix';// Create storage service with S3
const storage = new S3CDN({
accessKey: 'your_access_key',
secretKey: 'your_secret_key',
bucket: 'your_bucket',
region: 'us-east-1',
endpoint: 'https://nyc3.digitaloceanspaces.com' // Optional, for custom endpoints
});
`$3
`typescript
import { CloudflareR2CDN } from '@hyperplex/hyperflix';// Create storage service with Cloudflare R2
const storage = new CloudflareR2CDN({
accountId: 'your_cloudflare_account_id',
accessKeyId: 'your_r2_access_key',
secretAccessKey: 'your_r2_secret_key',
bucket: 'your_r2_bucket',
publicUrl: 'https://your-custom-domain.com' // Optional, for public URLs
});
`$3
`typescript
import { MockStorageService } from '@hyperplex/hyperflix';// Create a mock storage service for testing
const storage = new MockStorageService();
`$3
`typescript
import { createCDNService } from '@hyperplex/hyperflix';// Create a Vercel storage service
const vercelStorage = createCDNService('vercel', { token: 'your_token' });
// Create an S3 storage service
const s3Storage = createCDNService('s3', {
accessKey: 'your_access_key',
secretKey: 'your_secret_key',
bucket: 'your_bucket'
});
// Create a Cloudflare R2 storage service
const r2Storage = createCDNService('r2', {
accountId: 'your_cloudflare_account_id',
accessKeyId: 'your_r2_access_key',
secretAccessKey: 'your_r2_secret_key',
bucket: 'your_r2_bucket'
});
`🎥 Camera Motions
HyperFlix supports all LumaAI camera motions:
| Motion | Description |
|--------|-------------|
|
zoom-in / zoom-out | Zoom camera in or out |
| pan-left / pan-right | Pan camera horizontally |
| tilt-up / tilt-down | Tilt camera vertically |
| crane-up / crane-down | Move camera up or down |
| rotate-left / rotate-right | Rotate camera |
| dolly-in / dolly-out | Move camera towards/away from subject |🌐 Demo
View the demo by running:
`bash
npm run dev
or
yarn dev
``This will start a local web server and open the demo page in your browser.
MIT © Hyperplex Research Centre