@tanstack/ai/dist/esm/activities/generateVideo/index.d.ts

Core TanStack AI library - Open source AI SDK

import { VideoAdapter } from './adapter.js';
import { StreamChunk, VideoJobResult, VideoStatusResult, VideoUrlResult } from '../../types.js';
/** The adapter kind this activity handles */
export declare const kind: "video";
/**
 * Extract provider options from a VideoAdapter via ~types.
 */
export type VideoProviderOptions<TAdapter> = TAdapter extends VideoAdapter<any, any, any, any> ? TAdapter['~types']['providerOptions'] : object;
/**
 * Extract the size type for a VideoAdapter's model via ~types.
 */
export type VideoSizeForAdapter<TAdapter> = TAdapter extends VideoAdapter<infer TModel, any, any, infer TSizeMap> ? TModel extends keyof TSizeMap ? TSizeMap[TModel] : string : string;
/**
 * Base options shared by all video activity operations.
 * The model is extracted from the adapter's model property.
 */
interface VideoActivityBaseOptions<TAdapter extends VideoAdapter<string, any, any, any>> {
    /** The video adapter to use (must be created with a model) */
    adapter: TAdapter & {
        kind: typeof kind;
    };
}
/**
 * Options for creating a new video generation job.
 * The model is extracted from the adapter's model property.
 *
 * @template TAdapter - The video adapter type
 * @template TStream - Whether to stream the output
 *
 * @experimental Video generation is an experimental feature and may change.
 */
export type VideoCreateOptions<TAdapter extends VideoAdapter<string, any, any, any>, TStream extends boolean = false> = VideoActivityBaseOptions<TAdapter> & {
    /** Request type - create a new job (default if not specified) */
    request?: 'create';
    /** Text description of the desired video */
    prompt: string;
    /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
    size?: VideoSizeForAdapter<TAdapter>;
    /** Video duration in seconds */
    duration?: number;
    /**
     * Whether to stream the video generation lifecycle.
     * When true, returns an AsyncIterable<StreamChunk> that handles the full
     * job lifecycle: create job, poll for status, yield updates, and yield final result.
     * When false or not provided, returns a Promise<VideoJobResult>.
     *
     * @default false
     */
    stream?: TStream;
    /** Polling interval in milliseconds (stream mode only). @default 2000 */
    pollingInterval?: number;
    /** Maximum time to wait before timing out in milliseconds (stream mode only). @default 600000 */
    maxDuration?: number;
    /** Custom run ID (stream mode only) */
    runId?: string;
} & ({} extends VideoProviderOptions<TAdapter> ? {
    /** Provider-specific options for video generation */ modelOptions?: VideoProviderOptions<TAdapter>;
} : {
    /** Provider-specific options for video generation */ modelOptions: VideoProviderOptions<TAdapter>;
});
/**
 * Options for polling the status of a video generation job.
 *
 * @experimental Video generation is an experimental feature and may change.
 */
export interface VideoStatusOptions<TAdapter extends VideoAdapter<string, any, any, any>> extends VideoActivityBaseOptions<TAdapter> {
    /** Request type - get job status */
    request: 'status';
    /** The job ID to check status for */
    jobId: string;
}
/**
 * Options for getting the URL of a completed video.
 *
 * @experimental Video generation is an experimental feature and may change.
 */
export interface VideoUrlOptions<TAdapter extends VideoAdapter<string, any, any, any>> extends VideoActivityBaseOptions<TAdapter> {
    /** Request type - get video URL */
    request: 'url';
    /** The job ID to get URL for */
    jobId: string;
}
/**
 * Union type for all video activity options.
 * Discriminated by the `request` field.
 *
 * @experimental Video generation is an experimental feature and may change.
 */
export type VideoActivityOptions<TAdapter extends VideoAdapter<string, any, any, any>, TRequest extends 'create' | 'status' | 'url' = 'create', TStream extends boolean = false> = TRequest extends 'status' ? VideoStatusOptions<TAdapter> : TRequest extends 'url' ? VideoUrlOptions<TAdapter> : VideoCreateOptions<TAdapter, TStream>;
/**
 * Result type for the video activity, based on request type and streaming.
 * - If stream is true (create request): AsyncIterable<StreamChunk>
 * - Otherwise: Promise<VideoJobResult | VideoStatusResult | VideoUrlResult>
 *
 * @experimental Video generation is an experimental feature and may change.
 */
export type VideoActivityResult<TRequest extends 'create' | 'status' | 'url' = 'create', TStream extends boolean = false> = TRequest extends 'status' ? Promise<VideoStatusResult> : TRequest extends 'url' ? Promise<VideoUrlResult> : TStream extends true ? AsyncIterable<StreamChunk> : Promise<VideoJobResult>;
/**
 * Generate video - creates a video generation job from a text prompt.
 *
 * Uses AI video generation models to create videos based on natural language descriptions.
 * Unlike image generation, video generation is asynchronous and requires polling for completion.
 *
 * When `stream: true` is passed, handles the full job lifecycle automatically:
 * create job → poll for status → stream updates → yield final result.
 *
 * @experimental Video generation is an experimental feature and may change.
 *
 * @example Create a video generation job
 * ```ts
 * import { generateVideo } from '@tanstack/ai'
 * import { openaiVideo } from '@tanstack/ai-openai'
 *
 * // Start a video generation job
 * const { jobId } = await generateVideo({
 *   adapter: openaiVideo('sora-2'),
 *   prompt: 'A cat chasing a dog in a sunny park'
 * })
 *
 * console.log('Job started:', jobId)
 * ```
 *
 * @example Stream the full video generation lifecycle
 * ```ts
 * import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai'
 * import { openaiVideo } from '@tanstack/ai-openai'
 *
 * const stream = generateVideo({
 *   adapter: openaiVideo('sora-2'),
 *   prompt: 'A cat chasing a dog in a sunny park',
 *   stream: true,
 *   pollingInterval: 3000,
 * })
 *
 * return toServerSentEventsResponse(stream)
 * ```
 */
export declare function generateVideo<TAdapter extends VideoAdapter<string, any, any, any>, TStream extends boolean = false>(options: VideoCreateOptions<TAdapter, TStream>): VideoActivityResult<'create', TStream>;
/**
 * Get video job status - returns the current status, progress, and URL if available.
 *
 * This function combines status checking and URL retrieval. If the job is completed,
 * it will automatically fetch and include the video URL.
 *
 * @experimental Video generation is an experimental feature and may change.
 *
 * @example Check job status
 * ```ts
 * import { getVideoJobStatus } from '@tanstack/ai'
 * import { openaiVideo } from '@tanstack/ai-openai'
 *
 * const result = await getVideoJobStatus({
 *   adapter: openaiVideo('sora-2'),
 *   jobId: 'job-123'
 * })
 *
 * console.log('Status:', result.status)
 * console.log('Progress:', result.progress)
 * if (result.url) {
 *   console.log('Video URL:', result.url)
 * }
 * ```
 */
export declare function getVideoJobStatus<TAdapter extends VideoAdapter<string, any, any, any>>(options: {
    adapter: TAdapter & {
        kind: typeof kind;
    };
    jobId: string;
}): Promise<{
    status: 'pending' | 'processing' | 'completed' | 'failed';
    progress?: number;
    url?: string;
    error?: string;
}>;
/**
 * Create typed options for the generateVideo() function without executing.
 */
export declare function createVideoOptions<TAdapter extends VideoAdapter<string, any, any, any>, TStream extends boolean = false>(options: VideoCreateOptions<TAdapter, TStream>): VideoCreateOptions<TAdapter, TStream>;
export type { VideoAdapter, VideoAdapterConfig, AnyVideoAdapter, } from './adapter.js';
export { BaseVideoAdapter } from './adapter.js';