Interface ImageToVideoRequest

Request payload for image-to-video generation.

Passed to IVideoGenerator.imageToVideo by the high-level orchestration layer. Requires a source image that serves as the first frame (or style reference) for the generated video.

interface ImageToVideoRequest {
    modelId?: string;
    image: VideoImageInput;
    prompt: string;
    negativePrompt?: string;
    durationSec?: number;
    aspectRatio?: VideoAspectRatio;
    resolution?: string;
    referenceImages?: VideoImageInput[];
    outputFormat?: VideoOutputFormat;
    fps?: number;
    seed?: number;
    userId?: string;
    providerOptions?: Record<string, unknown> | VideoProviderOptionBag;
}

Properties

modelId? image prompt negativePrompt? durationSec? aspectRatio? resolution? referenceImages? outputFormat? fps? seed? userId? providerOptions?

Properties

Optional modelId

modelId?: string

Model identifier to use for generation.

image

image: VideoImageInput

Source image (the first frame): raw bytes, an https:// URL or a data: URL. See VideoImageInput for how each provider sends it. A custom provider that sends a URL can pass it through videoImageToUrl() (from the video index), which leaves a string as it is and turns a Buffer into a data: URL. A string reaches a provider only when the caller passed one.

prompt

prompt: string

Text prompt describing the desired motion / narrative.

Optional negativePrompt

negativePrompt?: string

Negative prompt describing content to avoid.

Optional durationSec

durationSec?: number

Desired output duration in seconds.

Optional aspectRatio

aspectRatio?: VideoAspectRatio

Desired aspect ratio.

Optional resolution

resolution?: string

Desired output resolution, in the model's own vocabulary (for example '720p', '1080p', or fal's '768P' for MiniMax). Sent as given.

Optional referenceImages

referenceImages?: VideoImageInput[]

Images of subjects or assets the video must keep consistent, besides the source image. Sent as fal's reference_image_urls, Replicate's reference_images, or Gemini image parts after the source image.

Optional outputFormat

outputFormat?: VideoOutputFormat

Output container format. Defaults to 'mp4'.

Optional fps

fps?: number

Frames per second for the output video.

Optional seed

seed?: number

Seed for reproducible output.

Optional userId

userId?: string

Identifier of the requesting user.

Optional providerOptions

providerOptions?: Record<string, unknown> | VideoProviderOptionBag

Provider-specific model inputs: a VideoProviderOptionBag keyed by provider id, or a flat object that fal, Replicate and Gemini receive whole.

Settings

Member Visibility

Theme

On This Page

modelIdimagepromptnegativePromptdurationSecaspectRatioresolutionreferenceImagesoutputFormatfpsseeduserIdproviderOptions