oneringaiv2
Documentation/Video Generation
v2.0.0-beta.1Snapshot bebdcd1Markdown ↗

Video Generation

Video Generation

Generate videos from text prompts

VideoGeneration class

📍 src/capabilities/video/VideoGeneration.ts:86

VideoGeneration capability class

Static Methods

static create()

Create a VideoGeneration instance

typescript
static create(options: VideoGenerationCreateOptions): VideoGeneration

Parameters:

  • options: VideoGenerationCreateOptions

Returns: VideoGeneration

Methods

generate()

Generate a video from a text prompt Returns a job that can be polled for completion

typescript
async generate(options: SimpleVideoGenerateOptions): Promise<VideoResponse>

Parameters:

  • options: SimpleVideoGenerateOptions

Returns: Promise<VideoResponse>

getStatus()

Get the status of a video generation job

typescript
async getStatus(jobId: string): Promise<VideoResponse>

Parameters:

  • jobId: string

Returns: Promise<VideoResponse>

waitForCompletion()

Wait for a video generation job to complete

typescript
async waitForCompletion(jobId: string, timeoutMs: number = 600000): Promise<VideoResponse>

Parameters:

  • jobId: string
  • timeoutMs: number (optional) (default: 600000)

Returns: Promise<VideoResponse>

download()

Download a completed video

typescript
async download(jobId: string): Promise<Buffer>

Parameters:

  • jobId: string

Returns: Promise<Buffer<ArrayBufferLike>>

generateAndWait()

Generate and wait for completion in one call

typescript
async generateAndWait(
    options: SimpleVideoGenerateOptions,
    timeoutMs: number = 600000
  ): Promise<VideoResponse>

Parameters:

  • options: SimpleVideoGenerateOptions
  • timeoutMs: number (optional) (default: 600000)

Returns: Promise<VideoResponse>

extend()

Extend an existing video Note: Not all models/vendors support this

typescript
async extend(options: SimpleVideoExtendOptions): Promise<VideoResponse>

Parameters:

  • options: SimpleVideoExtendOptions

Returns: Promise<VideoResponse>

remix()

Remix a completed video with a new prompt — same length, prompt-steered re-generation. Provider-dependent.

typescript
async remix(options: VideoRemixOptions): Promise<VideoResponse>

Parameters:

  • options: VideoRemixOptions

Returns: Promise<VideoResponse>

edit()

Edit a completed video using a prompt-described change. Provider-dependent.

typescript
async edit(options: VideoEditOptions): Promise<VideoResponse>

Parameters:

  • options: VideoEditOptions

Returns: Promise<VideoResponse>

createCharacter()

Create a reusable character from a reference video. Provider-dependent. Returns a CharacterRef whose id can be passed back via vendorOptions.characterId on a later generate call.

typescript
async createCharacter(options: CreateCharacterOptions): Promise<CharacterRef>

Parameters:

  • options: CreateCharacterOptions

Returns: Promise<CharacterRef>

getCharacter()

Look up an existing character by id. Provider-dependent.

typescript
async getCharacter(characterId: string): Promise<CharacterRef>

Parameters:

  • characterId: string

Returns: Promise<CharacterRef>

cancel()

Cancel a pending video generation job

typescript
async cancel(jobId: string): Promise<boolean>

Parameters:

  • jobId: string

Returns: Promise<boolean>

listModels()

List available models for this provider

typescript
async listModels(): Promise<string[]>

Returns: Promise<string[]>

getModelInfo()

Get information about a specific model

typescript
getModelInfo(modelName: string)

Parameters:

  • modelName: string

Returns: IVideoModelDescription | undefined

getProvider()

Get the underlying provider

typescript
getProvider(): IVideoProvider

Returns: IVideoProvider

getConnector()

Get the current connector

typescript
getConnector(): Connector

Returns: Connector

CharacterRef interface

📍 src/domain/interfaces/IVideoProvider.ts:84

A reusable character reference (Sora character API).

Properties
Property Type Description
id id: string; Character identifier returned by the provider
name name: string; Display name

CreateCharacterOptions interface

📍 src/domain/interfaces/IVideoProvider.ts:74

Options for creating a reusable character from a reference video (Sora character API).

Properties
Property Type Description
name name: string; Display name for the character
video `video: Buffer string;`

IVideoModelDescription interface

📍 src/domain/entities/VideoModel.ts:66

Video model description

Properties
Property Type Description
capabilities capabilities: VideoModelCapabilities; -
pricing? pricing?: VideoModelPricing; -

IVideoProvider interface

📍 src/domain/interfaces/IVideoProvider.ts:151

Video provider interface

Methods

generateVideo()

Generate a video from a text prompt Returns a job that can be polled for completion

typescript
generateVideo(options: VideoGenerateOptions): Promise<VideoResponse>;

Parameters:

  • options: VideoGenerateOptions

Returns: Promise<VideoResponse>

getVideoStatus()

Get the status of a video generation job

typescript
getVideoStatus(jobId: string): Promise<VideoResponse>;

Parameters:

  • jobId: string

Returns: Promise<VideoResponse>

downloadVideo()?

Download a completed video

typescript
downloadVideo?(jobId: string): Promise<Buffer>;

Parameters:

  • jobId: string

Returns: Promise<Buffer<ArrayBufferLike>>

extendVideo()?

Extend an existing video (optional)

typescript
extendVideo?(options: VideoExtendOptions): Promise<VideoResponse>;

Parameters:

  • options: VideoExtendOptions

Returns: Promise<VideoResponse>

remixVideo()?

Remix a completed video with a new prompt (optional). Distinct from extend: same length, prompt-steered re-generation.

typescript
remixVideo?(options: VideoRemixOptions): Promise<VideoResponse>;

Parameters:

  • options: VideoRemixOptions

Returns: Promise<VideoResponse>

editVideo()?

Edit a completed video using a prompt (optional).

typescript
editVideo?(options: VideoEditOptions): Promise<VideoResponse>;

Parameters:

  • options: VideoEditOptions

Returns: Promise<VideoResponse>

createCharacter()?

Create a reusable character from a reference video (optional). Returns a CharacterRef whose id can be threaded into future generateVideo calls via vendorOptions.

typescript
createCharacter?(options: CreateCharacterOptions): Promise<CharacterRef>;

Parameters:

  • options: CreateCharacterOptions

Returns: Promise<CharacterRef>

getCharacter()?

Look up an existing character by id (optional).

typescript
getCharacter?(characterId: string): Promise<CharacterRef>;

Parameters:

  • characterId: string

Returns: Promise<CharacterRef>

listModels()?

List available video models

typescript
listModels?(): Promise<string[]>;

Returns: Promise<string[]>

cancelJob()?

Cancel a pending video generation job

typescript
cancelJob?(jobId: string): Promise<boolean>;

Parameters:

  • jobId: string

Returns: Promise<boolean>

SimpleVideoGenerateOptions interface

📍 src/capabilities/video/VideoGeneration.ts:61

Simplified options for quick generation

Properties
Property Type Description
prompt prompt: string; Text prompt describing the video
model? model?: string; Model to use (defaults to vendor's best model)
duration? duration?: number; Duration in seconds
resolution? resolution?: string; Output resolution (e.g., '1280x720', '1920x1080')
aspectRatio? `aspectRatio?: '16:9' '9:16'
image? `image?: Buffer string;`
seed? seed?: number; Seed for reproducibility
vendorOptions? vendorOptions?: Record<string, unknown>; Vendor-specific options

VideoEditOptions interface

📍 src/domain/interfaces/IVideoProvider.ts:61

Options for editing an existing video. Edit = apply a prompt-described change to a completed video.

Properties
Property Type Description
model? model?: string; Model to use when the provider exposes multiple editing models.
videoId videoId: string; Identifier of the completed video to edit
prompt prompt: string; Prompt describing the edit

VideoExtendOptions interface

📍 src/domain/interfaces/IVideoProvider.ts:32

Options for extending an existing video

Properties
Property Type Description
model model: string; Model to use
video `video: Buffer string;`
prompt? prompt?: string; Optional prompt for the extension
extendDuration extendDuration: number; Duration to add in seconds
direction? `direction?: 'start' 'end';`

VideoGenerateOptions interface

📍 src/domain/interfaces/IVideoProvider.ts:10

Options for generating a video

Properties
Property Type Description
model model: string; Model to use
prompt prompt: string; Text prompt describing the video
duration? duration?: number; Duration in seconds
resolution? resolution?: string; Output resolution (e.g., '1280x720', '1920x1080')
aspectRatio? `aspectRatio?: '16:9' '9:16'
image? `image?: Buffer string;`
seed? seed?: number; Seed for reproducibility
vendorOptions? vendorOptions?: Record<string, unknown>; Vendor-specific options

VideoGenerationCreateOptions interface

📍 src/capabilities/video/VideoGeneration.ts:53

Options for creating a VideoGeneration instance

Properties
Property Type Description
connector `connector: string Connector;`

VideoJob interface

📍 src/domain/interfaces/IVideoProvider.ts:99

Video generation job

Properties
Property Type Description
id id: string; Job ID
status status: VideoStatus; Current status
createdAt createdAt: number; Timestamp when created
completedAt? completedAt?: number; Timestamp when completed (if applicable)
error? error?: string; Error message if failed
progress? progress?: number; Progress percentage (0-100)

VideoModelCapabilities interface

📍 src/domain/entities/VideoModel.ts:15

Video model capabilities

Properties
Property Type Description
durations durations: number[]; Supported durations in seconds
resolutions resolutions: string[]; Supported resolutions (e.g., '720p', '1080p', '720x1280')
aspectRatios? aspectRatios?: string[]; Supported aspect ratios (e.g., '16:9', '9:16') - for vendors that use this instead of resolution
maxFps maxFps: number; Maximum frames per second
audio audio: boolean; Whether the model supports audio generation
textToVideo? textToVideo?: boolean; Supports generation from only a text prompt. Defaults to true for legacy entries.
imageToVideo imageToVideo: boolean; Whether the model supports image-to-video
videoExtension videoExtension: boolean; Whether the model supports video extension
frameControl frameControl: boolean; Whether the model supports first/last frame specification
features `features: { 
/** Supports upscaling output */
upscaling: boolean;
/** Supports style/mood control */
styleControl: boolean;
/** Supports negative prompts */
negativePrompt: boolean;
/** Supports seed for reproducibility */
seed: boolean;

};` | Additional features |

VideoModelPricing interface

📍 src/domain/entities/VideoModel.ts:50

Video model pricing

Properties
Property Type Description
perSecond perSecond: number; Cost per second of generated video
perSecondByResolution? perSecondByResolution?: Readonly<Record<string, number>>; Resolution-specific rates when the provider does not use a flat rate.
batchPerSecondByResolution? batchPerSecondByResolution?: Readonly<Record<string, number>>; Discounted offline/batch rate when supported.
inputImage? inputImage?: number; Optional charge for an image-to-video reference image.
currency currency: string; Currency

VideoRemixOptions interface

📍 src/domain/interfaces/IVideoProvider.ts:50

Options for remixing an existing video. Remix = re-generate the same clip with a new prompt steering the result. The video reference is the completed-video ID returned by generateVideo.

Properties
Property Type Description
videoId videoId: string; Identifier of the completed video to remix
prompt prompt: string; Prompt steering the remix

VideoResponse interface

📍 src/domain/interfaces/IVideoProvider.ts:117

Video generation response

Properties
Property Type Description
jobId jobId: string; Job ID for tracking
status status: VideoStatus; Current status
created created: number; Timestamp when created
progress? progress?: number; Progress percentage (0-100)
video? `video?: { 
/** URL to download the video (if available) */
url?: string;
/** Base64 encoded video data */
b64_json?: string;
/** Duration in seconds */
duration?: number;
/** Resolution */
resolution?: string;
/** Format (e.g., 'mp4', 'webm') */
format?: string;

};| Generated video data (when complete) | |audio?|audio?: { url?: string; b64_json?: string; };| Audio track info (if separate) | |error?|error?: string;` | Error if failed |

SimpleVideoExtendOptions type

📍 src/capabilities/video/VideoGeneration.ts:81

High-level extension options; the current extend-capable model is selected when omitted.

typescript
type SimpleVideoExtendOptions = Omit<VideoExtendOptions, 'model'> & { model?: string }

VideoStatus type

📍 src/domain/interfaces/IVideoProvider.ts:94

Video generation status (for async operations)

typescript
type VideoStatus = 'pending' | 'processing' | 'completed' | 'failed'

calculateVideoCost function

📍 src/domain/entities/VideoModel.ts:505

Calculate video generation cost

typescript
export function calculateVideoCost(
  modelName: string,
  durationSeconds: number,
  options?: { resolution?: string; batch?: boolean; inputImages?: number }
): number | null

createVideoProvider function

📍 src/core/createVideoProvider.ts:16

Create a video provider from a connector

typescript
export function createVideoProvider(connector: Connector): IVideoProvider

createVideoTools function

📍 src/tools/multimedia/videoGeneration.ts:50

typescript
export function createVideoTools(
  connector: Connector,
  storage?: IMediaStorage,
  userId?: string
): ToolFunction[]

getVideoModelsWithAudio function

📍 src/domain/entities/VideoModel.ts:498

Get models that support audio

typescript
export function getVideoModelsWithAudio(): IVideoModelDescription[]

getVideoModelsWithFeature function

📍 src/domain/entities/VideoModel.ts:489

Get models with a specific feature

typescript
export function getVideoModelsWithFeature(feature: keyof VideoModelCapabilities['features']): IVideoModelDescription[]

VIDEO_MODEL_REGISTRY const

📍 src/domain/entities/VideoModel.ts:127

Video Model Registry

Properties
Property Type Description
'sora-2' `{ 
name: 'sora-2',
displayName: 'Sora 2',
provider: Vendor.OpenAI,
description: 'Retired video generation model; OpenAI shut down the Videos API with no replacement',
isActive: false,
lifecycle: 'retired',
availability: 'public',
deprecationDate: '2026-03-24',
retirementDate: '2026-09-24',
endpoints: ['video_generation', 'video_edit', 'batch'],
releaseDate: '2025-10-06',
sources: OPENAI_SOURCES,
capabilities: {
  durations: [4, 8, 12, 16, 20],
  resolutions: ['720x1280', '1280x720'],
  aspectRatios: ['9:16', '16:9'],
  maxFps: 30,
  audio: true,
  textToVideo: true,
  imageToVideo: true,
  videoExtension: true,
  frameControl: false,
  features: { upscaling: false, styleControl: false, negativePrompt: false, seed: true },
},
pricing: {
  perSecond: 0.10,
  perSecondByResolution: { '720p': 0.10, '720x1280': 0.10, '1280x720': 0.10 },
  batchPerSecondByResolution: { '720p': 0.05, '720x1280': 0.05, '1280x720': 0.05 },
  currency: 'USD',
},

}| - | |'sora-2-pro'|{ name: 'sora-2-pro', displayName: 'Sora 2 Pro', provider: Vendor.OpenAI, description: 'Retired high-resolution video generation model; OpenAI shut down the Videos API with no replacement', isActive: false, lifecycle: 'retired', availability: 'public', deprecationDate: '2026-03-24', retirementDate: '2026-09-24', endpoints: ['video_generation', 'video_edit', 'batch'], releaseDate: '2025-10-06', sources: OPENAI_SOURCES, capabilities: { durations: [4, 8, 12, 16, 20], resolutions: ['720x1280', '1280x720', '1024x1792', '1792x1024', '1080x1920', '1920x1080'], aspectRatios: ['9:16', '16:9'], maxFps: 30, audio: true, textToVideo: true, imageToVideo: true, videoExtension: true, frameControl: true, features: { upscaling: true, styleControl: true, negativePrompt: false, seed: true }, }, pricing: { perSecond: 0.30, perSecondByResolution: { '720p': 0.30, '720x1280': 0.30, '1280x720': 0.30, '1024p': 0.50, '1024x1792': 0.50, '1792x1024': 0.50, '1080p': 0.70, '1080x1920': 0.70, '1920x1080': 0.70, }, batchPerSecondByResolution: { '720p': 0.15, '720x1280': 0.15, '1280x720': 0.15, '1024p': 0.25, '1024x1792': 0.25, '1792x1024': 0.25, '1080p': 0.35, '1080x1920': 0.35, '1920x1080': 0.35, }, currency: 'USD', }, }| - | |'veo-2.0-generate-001'|{ name: 'veo-2.0-generate-001', displayName: 'Veo 2.0', provider: Vendor.Google, isActive: false, lifecycle: 'retired', retirementDate: '2026-06-30', replacementModel: 'veo-3.1-lite-generate-preview', sources: GOOGLE_SOURCES, capabilities: { durations: [5, 6, 7, 8], resolutions: ['720p'], // Veo 2 only supports 720p aspectRatios: ['16:9', '9:16'], maxFps: 24, audio: false, imageToVideo: false, // Veo 2 does not support reference images videoExtension: false, frameControl: true, // First/last frame interpolation supported features: { upscaling: false, styleControl: false, negativePrompt: true, seed: true, }, }, pricing: { perSecond: 0.35, // Updated per official pricing page (was $0.03) currency: 'USD', }, }| - | |'veo-3.1-fast-generate-preview'|{ name: 'veo-3.1-fast-generate-preview', displayName: 'Veo 3.1 Fast', provider: Vendor.Google, isActive: true, sources: GOOGLE_SOURCES, capabilities: { durations: [4, 6, 8], resolutions: ['720p', '1080p', '4k'], // 1080p/4k require 8s duration aspectRatios: ['16:9', '9:16'], maxFps: 24, audio: true, // Native audio generation imageToVideo: true, // Up to 3 reference images videoExtension: true, // Supported (720p only) frameControl: true, // First/last frame interpolation features: { upscaling: false, styleControl: false, negativePrompt: true, seed: true, }, }, pricing: { perSecond: 0.10, perSecondByResolution: { '720p': 0.10, '1080p': 0.12, '4k': 0.30 }, currency: 'USD', }, }| - | |'veo-3.1-generate-preview'|{ name: 'veo-3.1-generate-preview', displayName: 'Veo 3.1', provider: Vendor.Google, isActive: true, sources: GOOGLE_SOURCES, capabilities: { durations: [4, 6, 8], resolutions: ['720p', '1080p', '4k'], // 1080p and 4k require 8s duration aspectRatios: ['16:9', '9:16'], maxFps: 30, audio: true, // Native audio generation imageToVideo: true, // Up to 3 reference images videoExtension: true, // Supported (720p only) frameControl: true, features: { upscaling: true, styleControl: true, negativePrompt: true, seed: true, }, }, pricing: { perSecond: 0.40, // $0.40 for 720p/1080p, $0.60 for 4K perSecondByResolution: { '720p': 0.40, '1080p': 0.40, '4k': 0.60 }, currency: 'USD', }, }| - | |'veo-3.1-lite-generate-preview'|{ name: 'veo-3.1-lite-generate-preview', displayName: 'Veo 3.1 Lite', provider: Vendor.Google, description: 'Cost-efficient Veo 3.1 preview for short 720p and 1080p clips with native audio', isActive: true, lifecycle: 'preview', availability: 'public', preferred: true, endpoints: ['video_generation'], releaseDate: '2026-06-30', sources: { ...GOOGLE_SOURCES, lastVerified: '2026-08-30' }, capabilities: { durations: [4, 6, 8], resolutions: ['720p', '1080p'], aspectRatios: ['16:9', '9:16'], maxFps: 24, audio: true, imageToVideo: true, videoExtension: false, frameControl: true, features: { upscaling: false, styleControl: false, negativePrompt: true, seed: true }, }, pricing: { perSecond: 0.05, perSecondByResolution: { '720p': 0.05, '1080p': 0.08 }, currency: 'USD', }, }| - | |'gemini-omni-flash-preview'|{ name: 'gemini-omni-flash-preview', displayName: 'Gemini Omni Flash', provider: Vendor.Google, description: 'Conversational 720p video generation and editing through the Interactions API', isActive: true, lifecycle: 'deprecated', availability: 'public', deprecationDate: '2026-08-27', retirementDate: '2026-09-30', replacementModel: 'gemini-omni-1.1-flash', endpoints: ['interactions', 'video_generation', 'video_edit'], releaseDate: '2026-06-30', sources: { documentation: 'https://ai.google.dev/gemini-api/docs/omni', apiReference: 'https://ai.google.dev/api/interactions-api', lastVerified: '2026-08-30', }, capabilities: { durations: [3, 4, 5, 6, 7, 8, 9, 10], resolutions: ['720p'], aspectRatios: ['16:9', '9:16'], maxFps: 24, audio: true, imageToVideo: true, videoExtension: false, frameControl: false, features: { upscaling: false, styleControl: true, negativePrompt: false, seed: false }, }, pricing: { perSecond: 0.10, perSecondByResolution: { '720p': 0.10 }, currency: 'USD' }, }| - | |'gemini-omni-1.1-flash'|{ name: 'gemini-omni-1.1-flash', displayName: 'Gemini Omni 1.1 Flash', provider: Vendor.Google, description: 'Generally available conversational video generation and editing through the Interactions API', isActive: true, lifecycle: 'active', availability: 'public', preferred: true, endpoints: ['interactions', 'video_generation', 'video_edit'], releaseDate: '2026-08-27', sources: { documentation: 'https://ai.google.dev/gemini-api/docs/models/gemini-omni-flash', apiReference: 'https://ai.google.dev/api/interactions-api', pricing: 'https://ai.google.dev/gemini-api/docs/pricing', lastVerified: '2026-08-30', }, capabilities: { durations: [3, 4, 5, 6, 7, 8, 9, 10], resolutions: ['360p', '720p', '1080p', '4k'], aspectRatios: ['16:9', '9:16'], maxFps: 24, audio: true, textToVideo: true, imageToVideo: true, videoExtension: false, frameControl: false, features: { upscaling: true, styleControl: true, negativePrompt: false, seed: false }, }, pricing: { perSecond: 0.10, perSecondByResolution: { '720p': 0.10 }, currency: 'USD' }, }| - | |'grok-imagine-video'|{ name: 'grok-imagine-video', displayName: 'Grok Imagine Video', provider: Vendor.Grok, isActive: true, sources: GROK_SOURCES, capabilities: { durations: [1, 5, 8, 10, 15], resolutions: ['480p', '720p'], aspectRatios: ['16:9', '4:3', '1:1', '9:16', '3:4', '3:2', '2:3'], maxFps: 24, audio: true, imageToVideo: true, videoExtension: false, frameControl: false, features: { upscaling: false, styleControl: false, negativePrompt: false, seed: true, }, }, pricing: { perSecond: 0.05, perSecondByResolution: { '480p': 0.05, '720p': 0.07 }, currency: 'USD', }, }| - | |'grok-imagine-video-1.5'|{ name: 'grok-imagine-video-1.5', displayName: 'Grok Imagine Video 1.5', provider: Vendor.Grok, description: 'Higher-fidelity xAI video generation with 480p, 720p, and 1080p output', isActive: true, lifecycle: 'active', availability: 'public', preferred: true, aliases: ['grok-imagine-video-1.5-preview'], snapshots: ['grok-imagine-video-1.5-2026-05-30'], endpoints: ['video_generation'], releaseDate: '2026-06-01', sources: { documentation: 'https://docs.x.ai/developers/models/grok-imagine-video-1.5', pricing: 'https://docs.x.ai/developers/models/grok-imagine-video-1.5', lastVerified: '2026-08-30', }, capabilities: { durations: [1, 5, 8, 10, 15], resolutions: ['480p', '720p', '1080p'], aspectRatios: ['16:9', '4:3', '1:1', '9:16', '3:4', '3:2', '2:3'], maxFps: 24, audio: true, textToVideo: true, imageToVideo: true, videoExtension: false, frameControl: false, features: { upscaling: true, styleControl: true, negativePrompt: false, seed: true }, }, pricing: { perSecond: 0.08, perSecondByResolution: { '480p': 0.08, '720p': 0.14, '1080p': 0.25 }, inputImage: 0.01, currency: 'USD', }, }` | - |

Documentation snapshot · 2026-11-02Suggest a correction ↗

Search documentation

Type to search the v2 documentation.

↑ ↓ to navigate Esc to close