ai 7.0.49 → 7.0.50

package/src/generate-video/generate-video.ts

@@ -2,12 +2,15 @@ import type {
   Experimental_VideoModelV4,
   Experimental_VideoModelV4CallOptions,
   Experimental_VideoModelV4File,
+  Experimental_VideoModelV4Result,
+  Experimental_VideoModelV4OperationWebhook,
   Experimental_VideoModelV4FrameImage,
   Experimental_VideoModelV4FrameType,
   SharedV4ProviderMetadata,
 } from '@ai-sdk/provider';
 import {
   convertBase64ToUint8Array,
+  delay as defaultDelay,
   withUserAgentSuffix,
   type DataContent,
   detectMediaType,
@@ -19,6 +22,7 @@ import {
   type GeneratedFile,
 } from '../generate-text/generated-file';
 import { logWarnings } from '../logger/log-warnings';
+import { mergeAbortSignals } from '../util/merge-abort-signals';
 import { resolveVideoModel } from '../model/resolve-model';
 import type { VideoModel } from '../types/video-model';
 import type { VideoModelResponseMetadata } from '../types/video-model-response-metadata';
@@ -36,6 +40,52 @@ export type GenerateVideoPrompt =
       text?: string;
     };
 
+/**
+ * Polling configuration for models that support the asynchronous
+ * start/status flow.
+ *
+ * When used with `webhook`, `timeoutMs` also limits how long the SDK waits for
+ * the webhook notification. If the model does not support webhooks, these
+ * options configure the automatic polling fallback.
+ */
+export type GenerateVideoPollOptions = {
+  /**
+   * Interval between status checks in milliseconds.
+   *
+   * @default 5000
+   */
+  intervalMs?: number;
+
+  /**
+   * Maximum time to wait for completion in milliseconds.
+   *
+   * @default 600000 (10 minutes)
+   */
+  timeoutMs?: number;
+
+  /**
+   * Custom delay implementation for polling intervals and webhook timeouts.
+   * This can be used with durable workflow sleep functions.
+   *
+   * @default the built-in timer-based delay
+   */
+  delay?: (
+    delayInMs: number,
+    options?: { abortSignal?: AbortSignal },
+  ) => PromiseLike<void>;
+};
+
+/**
+ * Webhook factory for models that support the asynchronous start/status flow.
+ *
+ * The factory should return a URL for the provider to send notifications to,
+ * and a `received` promise that resolves when the notification arrives.
+ */
+export type GenerateVideoWebhookFactory = () => PromiseLike<{
+  url: string;
+  received: PromiseLike<Experimental_VideoModelV4OperationWebhook>;
+}>;
+
 /**
  * Generates videos using a video model.
  *
@@ -55,6 +105,8 @@ export type GenerateVideoPrompt =
  * @param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
  * @param abortSignal - An optional abort signal that can be used to cancel the call.
  * @param headers - Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
+ * @param poll - Polling configuration for models that support the start/status flow.
+ * @param webhook - Webhook factory for models that support the start/status flow.
  *
  * @returns A result object that contains the generated videos.
  */
@@ -78,6 +130,8 @@ export async function experimental_generateVideo({
   abortSignal,
   headers,
   download: downloadFn = defaultDownload,
+  poll,
+  webhook,
 }: {
   /**
    * The video model to use.
@@ -105,7 +159,7 @@ export async function experimental_generateVideo({
   aspectRatio?: `${number}:${number}`;
 
   /**
-   * Resolution of the videos to generate. Must have the format `{width}x{height}`.
+   * Resolution of the videos to generate. Must have the format `{width}x${height}`.
    */
   resolution?: `${number}x${number}`;
 
@@ -200,6 +254,29 @@ export async function experimental_generateVideo({
     url: URL;
     abortSignal?: AbortSignal;
   }) => Promise<{ data: Uint8Array; mediaType: string | undefined }>;
+
+  /**
+   * Polling configuration for models that support the asynchronous
+   * start/status flow. When provided and the model implements `doStart`
+   * and `doStatus`, the SDK will orchestrate polling automatically.
+   *
+   * This option can be combined with `webhook`: `timeoutMs` limits the webhook
+   * wait, and the polling settings apply if the model does not support
+   * webhooks.
+   */
+  poll?: GenerateVideoPollOptions;
+
+  /**
+   * Webhook factory for models that support the asynchronous
+   * start/status flow. When provided and the model implements `doStart`
+   * and `doStatus`, the SDK will use webhooks instead of polling.
+   *
+   * The factory should return a URL for the provider to send notifications to,
+   * and a `received` promise that resolves when the notification arrives.
+   * `poll` can also be provided to configure the webhook timeout and polling
+   * fallback.
+   */
+  webhook?: GenerateVideoWebhookFactory;
 }): Promise<GenerateVideoResult> {
   const model = resolveVideoModel(modelArg);
 
@@ -270,6 +347,34 @@ export async function experimental_generateVideo({
   const maxVideosPerCallWithDefault =
     maxVideosPerCall ?? (await invokeModelMaxVideosPerCall(model)) ?? 1;
 
+  // Determine whether to use the start/status flow:
+  const hasStartStatus = model.doStart != null && model.doStatus != null;
+  const useStartStatus =
+    hasStartStatus &&
+    (poll != null || webhook != null || model.doGenerate == null);
+
+  // Validate model capabilities
+  if (model.doGenerate == null && !hasStartStatus) {
+    throw new Error(
+      `Video model ${model.modelId} does not implement doGenerate or doStart/doStatus.`,
+    );
+  }
+
+  // Warn if poll/webhook provided but model doesn't support start/status
+  if ((poll != null || webhook != null) && !hasStartStatus) {
+    logWarnings({
+      warnings: [
+        {
+          type: 'other',
+          message:
+            'poll/webhook options were provided but the model does not support doStart/doStatus. Falling back to doGenerate.',
+        },
+      ],
+      provider: model.provider,
+      model: model.modelId,
+    });
+  }
+
   // parallelize calls to the model:
   const callCount = Math.ceil(n / maxVideosPerCallWithDefault);
   const callVideoCounts = Array.from({ length: callCount }, (_, index) => {
@@ -278,27 +383,36 @@ export async function experimental_generateVideo({
   });
 
   const results = await Promise.all(
-    callVideoCounts.map(
-      async callVideoCount =>
-        await retry(() =>
-          model.doGenerate({
-            prompt,
-            n: callVideoCount,
-            aspectRatio,
-            resolution,
-            duration,
-            fps,
-            seed,
-            image: resolvedImage,
-            frameImages: normalizedFrameImages,
-            inputReferences: effectiveInputReferences,
-            generateAudio,
-            providerOptions: providerOptions ?? {},
-            headers: headersWithUserAgent,
-            abortSignal,
-          } satisfies Experimental_VideoModelV4CallOptions),
-        ),
-    ),
+    callVideoCounts.map(async callVideoCount => {
+      const callOptions: Experimental_VideoModelV4CallOptions = {
+        prompt,
+        n: callVideoCount,
+        aspectRatio,
+        resolution,
+        duration,
+        fps,
+        seed,
+        image: resolvedImage,
+        frameImages: normalizedFrameImages,
+        inputReferences: effectiveInputReferences,
+        generateAudio,
+        providerOptions: providerOptions ?? {},
+        headers: headersWithUserAgent,
+        abortSignal,
+      };
+
+      if (useStartStatus) {
+        return executeStartStatusFlow({
+          model,
+          callOptions,
+          poll,
+          webhook,
+          retry,
+        });
+      }
+
+      return retry(() => model.doGenerate!(callOptions));
+    }),
   );
 
   // collect result videos, warnings, and response metadata
@@ -377,32 +491,7 @@ export async function experimental_generateVideo({
     });
 
     if (result.providerMetadata != null) {
-      for (const [providerName, metadata] of Object.entries(
-        result.providerMetadata,
-      )) {
-        const existingMetadata = providerMetadata[providerName];
-        if (existingMetadata != null && typeof existingMetadata === 'object') {
-          providerMetadata[providerName] = {
-            ...existingMetadata,
-            ...metadata,
-          };
-
-          // Merge videos arrays if both exist
-          if (
-            'videos' in existingMetadata &&
-            Array.isArray(existingMetadata.videos) &&
-            'videos' in metadata &&
-            Array.isArray(metadata.videos)
-          ) {
-            (providerMetadata[providerName] as { videos: unknown[] }).videos = [
-              ...existingMetadata.videos,
-              ...metadata.videos,
-            ];
-          }
-        } else {
-          providerMetadata[providerName] = metadata;
-        }
-      }
+      mergeProviderMetadata(providerMetadata, result.providerMetadata);
     }
   }
 
@@ -427,6 +516,197 @@ export async function experimental_generateVideo({
   };
 }
 
+async function executeStartStatusFlow({
+  model,
+  callOptions,
+  poll: pollConfig,
+  webhook: webhookFactory,
+  retry,
+}: {
+  model: Experimental_VideoModelV4;
+  callOptions: Experimental_VideoModelV4CallOptions;
+  poll?: GenerateVideoPollOptions;
+  webhook?: GenerateVideoWebhookFactory;
+  retry: <OUTPUT>(fn: () => PromiseLike<OUTPUT>) => PromiseLike<OUTPUT>;
+}): Promise<Experimental_VideoModelV4Result> {
+  // 1. If webhook and provider supports it, set up the webhook
+  const earlyWarnings: Experimental_VideoModelV4Result['warnings'] = [];
+  let webhookUrl: string | undefined;
+  let webhookReceived:
+    | PromiseLike<Experimental_VideoModelV4OperationWebhook>
+    | undefined;
+
+  if (webhookFactory != null) {
+    if (model.handleWebhookOption != null) {
+      const result = await model.handleWebhookOption({
+        webhook: webhookFactory,
+      });
+      webhookUrl = result.webhookUrl;
+      webhookReceived = result.received;
+    } else {
+      earlyWarnings.push({
+        type: 'unsupported',
+        feature: 'webhook',
+        details:
+          'This model does not support webhooks. Falling back to polling.',
+      });
+    }
+  }
+
+  // 2. Start the generation
+  const startResult = await retry(() =>
+    model.doStart!({
+      ...callOptions,
+      webhookUrl,
+    }),
+  );
+
+  const allWarnings = [...earlyWarnings, ...startResult.warnings];
+  let operationProviderMetadata =
+    startResult.providerMetadata == null
+      ? undefined
+      : { ...startResult.providerMetadata };
+  const intervalMs = pollConfig?.intervalMs ?? 5000;
+  const timeoutMs = pollConfig?.timeoutMs ?? 600_000;
+  const delay = pollConfig?.delay ?? defaultDelay;
+  const startTime = Date.now();
+
+  if (webhookReceived != null) {
+    // 3a. Webhook flow: wait for webhook, then get final status
+    await waitForWebhook({
+      received: webhookReceived,
+      timeoutMs,
+      abortSignal: callOptions.abortSignal,
+      delay,
+    });
+  }
+
+  while (true) {
+    if (webhookReceived == null) {
+      // 3b. Polling flow (also used when webhooks are not supported)
+      const elapsedMs = Date.now() - startTime;
+      if (elapsedMs >= timeoutMs) {
+        throw new Error(`Video generation timed out after ${timeoutMs}ms.`);
+      }
+      await delay(Math.min(intervalMs, timeoutMs - elapsedMs), {
+        abortSignal: callOptions.abortSignal,
+      });
+      if (Date.now() - startTime >= timeoutMs) {
+        throw new Error(`Video generation timed out after ${timeoutMs}ms.`);
+      }
+    }
+
+    const statusResult = await retry(() =>
+      model.doStatus!({
+        operation: startResult.operation,
+        abortSignal: callOptions.abortSignal,
+        headers: callOptions.headers,
+      }),
+    );
+
+    if (statusResult.status === 'error') {
+      throw new Error(statusResult.error);
+    }
+
+    if (statusResult.warnings != null) {
+      allWarnings.push(...statusResult.warnings);
+    }
+    if (statusResult.providerMetadata != null) {
+      operationProviderMetadata ??= {};
+      mergeProviderMetadata(
+        operationProviderMetadata,
+        statusResult.providerMetadata,
+      );
+    }
+
+    if (statusResult.status === 'completed') {
+      return {
+        videos: statusResult.videos,
+        warnings: allWarnings,
+        providerMetadata: operationProviderMetadata,
+        response: statusResult.response,
+      };
+    }
+
+    if (webhookReceived != null) {
+      throw new Error(
+        'Video generation did not complete after webhook notification.',
+      );
+    }
+  }
+}
+
+async function waitForWebhook({
+  received,
+  timeoutMs,
+  abortSignal,
+  delay,
+}: {
+  received: PromiseLike<Experimental_VideoModelV4OperationWebhook>;
+  timeoutMs: number;
+  abortSignal?: AbortSignal;
+  delay: (
+    delayInMs: number,
+    options?: { abortSignal?: AbortSignal },
+  ) => PromiseLike<void>;
+}) {
+  // Cancel the timeout delay once the webhook arrives (or we abort/time out),
+  // so its timer does not keep the event loop alive on the success path.
+  const timeoutController =
+    typeof globalThis.AbortController === 'function'
+      ? new globalThis.AbortController()
+      : undefined;
+  try {
+    await Promise.race([
+      received,
+      delay(timeoutMs, {
+        abortSignal:
+          timeoutController == null
+            ? abortSignal
+            : mergeAbortSignals(abortSignal, timeoutController.signal),
+      }).then(() => {
+        throw new Error(`Video generation timed out after ${timeoutMs}ms.`);
+      }),
+    ]);
+  } finally {
+    timeoutController?.abort();
+  }
+}
+
+function mergeProviderMetadata(
+  target: SharedV4ProviderMetadata,
+  source: SharedV4ProviderMetadata,
+): void {
+  for (const [providerName, metadataValue] of Object.entries(source)) {
+    const existingMetadata = target[providerName];
+    if (
+      existingMetadata != null &&
+      typeof existingMetadata === 'object' &&
+      metadataValue != null &&
+      typeof metadataValue === 'object'
+    ) {
+      target[providerName] = {
+        ...existingMetadata,
+        ...metadataValue,
+      };
+
+      if (
+        'videos' in existingMetadata &&
+        Array.isArray(existingMetadata.videos) &&
+        'videos' in metadataValue &&
+        Array.isArray(metadataValue.videos)
+      ) {
+        (target[providerName] as { videos: unknown[] }).videos = [
+          ...existingMetadata.videos,
+          ...metadataValue.videos,
+        ];
+      }
+    } else {
+      target[providerName] = metadataValue;
+    }
+  }
+}
+
 function normalizePrompt(promptArg: GenerateVideoPrompt): {
   prompt: string | undefined;
   image: Experimental_VideoModelV4File | undefined;

package/src/test/mock-video-model-v4.ts

@@ -8,21 +8,28 @@ export class MockVideoModelV4 implements Experimental_VideoModelV4 {
   readonly maxVideosPerCall: Experimental_VideoModelV4['maxVideosPerCall'];
 
   doGenerate: Experimental_VideoModelV4['doGenerate'];
+  handleWebhookOption: Experimental_VideoModelV4['handleWebhookOption'];
+  doStart: Experimental_VideoModelV4['doStart'];
+  doStatus: Experimental_VideoModelV4['doStatus'];
 
-  constructor({
-    provider = 'mock-provider',
-    modelId = 'mock-model-id',
-    maxVideosPerCall = 1,
-    doGenerate = notImplemented,
-  }: {
-    provider?: Experimental_VideoModelV4['provider'];
-    modelId?: Experimental_VideoModelV4['modelId'];
-    maxVideosPerCall?: Experimental_VideoModelV4['maxVideosPerCall'];
-    doGenerate?: Experimental_VideoModelV4['doGenerate'];
-  } = {}) {
-    this.provider = provider;
-    this.modelId = modelId;
-    this.maxVideosPerCall = maxVideosPerCall;
-    this.doGenerate = doGenerate;
+  constructor(
+    options: {
+      provider?: Experimental_VideoModelV4['provider'];
+      modelId?: Experimental_VideoModelV4['modelId'];
+      maxVideosPerCall?: Experimental_VideoModelV4['maxVideosPerCall'];
+      doGenerate?: Experimental_VideoModelV4['doGenerate'];
+      handleWebhookOption?: Experimental_VideoModelV4['handleWebhookOption'];
+      doStart?: Experimental_VideoModelV4['doStart'];
+      doStatus?: Experimental_VideoModelV4['doStatus'];
+    } = {},
+  ) {
+    this.provider = options.provider ?? 'mock-provider';
+    this.modelId = options.modelId ?? 'mock-model-id';
+    this.maxVideosPerCall = options.maxVideosPerCall ?? 1;
+    this.doGenerate =
+      'doGenerate' in options ? options.doGenerate : notImplemented;
+    this.handleWebhookOption = options.handleWebhookOption;
+    this.doStart = options.doStart;
+    this.doStatus = options.doStatus;
   }
 }