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?
optionalapiKey:string
Defined in: packages/agentos/src/api/generateVideo.ts:305
Override the provider API key instead of reading from env vars.
aspectRatio?
optionalaspectRatio:VideoAspectRatio
Defined in: packages/agentos/src/api/generateVideo.ts:263
Desired aspect ratio (e.g. "16:9", "9:16").
baseUrl?
optionalbaseUrl:string
Defined in: packages/agentos/src/api/generateVideo.ts:308
Override the provider base URL.
durationSec?
optionaldurationSec:number
Defined in: packages/agentos/src/api/generateVideo.ts:260
Desired output duration in seconds.
image?
optionalimage: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?
optionalmodel: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?
optionalnegativePrompt:string
Defined in: packages/agentos/src/api/generateVideo.ts:273
Negative prompt describing content to avoid.
onProgress()?
optionalonProgress: (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
Returns
void
prompt
prompt:
string
Defined in: packages/agentos/src/api/generateVideo.ts:220
Text prompt describing the desired video content.
provider?
optionalprovider: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?
optionalproviderOptions: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?
optionalproviderPreferences: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?
optionalreferenceImages: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?
optionalresolution: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?
optionalseed:number
Defined in: packages/agentos/src/api/generateVideo.ts:276
Random seed for reproducible generation (provider-dependent).
timeoutMs?
optionaltimeoutMs: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?
optionalusageLedger:AgentOSUsageLedgerOptions
Defined in: packages/agentos/src/api/generateVideo.ts:318
Optional durable usage ledger configuration for accounting.