Skip to main content

Interface: GenerateVideoOptions

Defined in: packages/agentos/src/api/generateVideo.ts:218

Options for a generateVideo call.

At minimum, a prompt is required. The provider is resolved from opts.provider, opts.apiKey, or the first video-capable env var found (RUNWAY_API_KEY -> REPLICATE_API_TOKEN -> FAL_API_KEY).

Properties​

apiKey?​

optional apiKey: string

Defined in: packages/agentos/src/api/generateVideo.ts:305

Override the provider API key instead of reading from env vars.


aspectRatio?​

optional aspectRatio: VideoAspectRatio

Defined in: packages/agentos/src/api/generateVideo.ts:263

Desired aspect ratio (e.g. "16:9", "9:16").


baseUrl?​

optional baseUrl: string

Defined in: packages/agentos/src/api/generateVideo.ts:308

Override the provider base URL.


durationSec?​

optional durationSec: number

Defined in: packages/agentos/src/api/generateVideo.ts:260

Desired output duration in seconds.


image?​

optional image: VideoImageInput

Defined in: packages/agentos/src/api/generateVideo.ts:233

Source image (the first frame) for image-to-video generation. When provided, the request is dispatched to imageToVideo() instead of generateVideo().

Accepts a Buffer, an https:// URL or a data: URL. fal, Replicate and Runway receive a URL as given and a Buffer as a data: URL; the Gemini provider fetches an https:// URL itself through the checked egress path (public addresses on port 443, each redirect checked) and sends the bytes inline.


model?​

optional model: string

Defined in: packages/agentos/src/api/generateVideo.ts:257

Model identifier within the provider (e.g. "fal-ai/minimax/hailuo-02/standard/image-to-video", "google/veo-3.1", "gemini-omni-1.1-flash"). When omitted, the provider picks its default, which on fal is a text-to-video or an image-to-video endpoint as the call needs.


negativePrompt?​

optional negativePrompt: string

Defined in: packages/agentos/src/api/generateVideo.ts:273

Negative prompt describing content to avoid.


onProgress()?​

optional onProgress: (event) => void

Defined in: packages/agentos/src/api/generateVideo.ts:302

Optional progress callback invoked during long-running generation. Called with a VideoProgressEvent at each status transition.

Parameters​

event​

VideoProgressEvent

Returns​

void


prompt​

prompt: string

Defined in: packages/agentos/src/api/generateVideo.ts:220

Text prompt describing the desired video content.


provider?​

optional provider: string

Defined in: packages/agentos/src/api/generateVideo.ts:248

Explicit provider identifier ("runway", "replicate", "fal" or "gemini"). When omitted, auto-detection from environment variables is used; "gemini" runs only when named here.


providerOptions?​

optional providerOptions: Record<string, unknown> | VideoProviderOptionBag

Defined in: packages/agentos/src/api/generateVideo.ts:296

Provider-specific model inputs the typed fields do not cover, such as fal's end_image_url or Replicate's last_frame.

Key them by provider id ({ fal: {...}, replicate: {...} }) so each provider in a fallback chain receives only its own entry; a bag with no provider-id key goes whole to fal, Replicate and Gemini. They add inputs and never replace a field the call sets: to send a model-specific value for such a field, leave the typed field unset and put the value here. Runway sends no provider options.


providerPreferences?​

optional providerPreferences: MediaProviderPreference

Defined in: packages/agentos/src/api/generateVideo.ts:315

Provider preferences for reordering or filtering the fallback chain. When supplied, the available video providers are reordered according to preferred and filtered by blocked before building the chain.


referenceImages?​

optional referenceImages: VideoImageInput[]

Defined in: packages/agentos/src/api/generateVideo.ts:241

Images of subjects or assets the video must keep consistent (reference-to-video), in the same forms as image. Sent as fal's reference_image_urls, Replicate's reference_images, or Gemini image parts after the source image.


resolution?​

optional resolution: string

Defined in: packages/agentos/src/api/generateVideo.ts:270

Desired output resolution, in the model's own vocabulary (e.g. "720p", "1080p", or "768P" for MiniMax on fal). Sent as given, for text-to-video and image-to-video.


seed?​

optional seed: number

Defined in: packages/agentos/src/api/generateVideo.ts:276

Random seed for reproducible generation (provider-dependent).


timeoutMs?​

optional timeoutMs: number

Defined in: packages/agentos/src/api/generateVideo.ts:283

Maximum time in milliseconds to wait for generation to complete, given to each provider at initialize(): the polling budget on fal, Replicate and Runway, and the deadline of every request on Gemini.


usageLedger?​

optional usageLedger: AgentOSUsageLedgerOptions

Defined in: packages/agentos/src/api/generateVideo.ts:318

Optional durable usage ledger configuration for accounting.