@ai-sdk/gateway 4.0.43 → 4.0.44

package/docs/00-ai-gateway.mdx

@@ -444,6 +444,29 @@ if (generationId) {
 }
 ```
 
+You can also capture the generation ID for every completed model call with
+`onLanguageModelCallEnd`. The callback runs before client-side tools execute,
+so the metadata remains available even if the operation is later aborted while
+a tool is running:
+
+```ts
+import { gateway, generateText } from 'ai';
+
+await generateText({
+  model: gateway('anthropic/claude-sonnet-4'),
+  prompt: 'Explain quantum entanglement briefly',
+  onLanguageModelCallEnd({ providerMetadata }) {
+    const generationId = providerMetadata?.gateway?.generationId as
+      | string
+      | undefined;
+
+    if (generationId) {
+      console.log(`Completed Gateway generation: ${generationId}`);
+    }
+  },
+});
+```
+
 The `getGenerationInfo()` method accepts:
 
 - **id** _string_ - The generation ID to look up (format: `gen_<ulid>`, required)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "4.0.43",
+  "version": "4.0.44",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,

package/src/gateway-video-model.ts

@@ -3,7 +3,10 @@ import {
   type Experimental_VideoModelV4 as VideoModelV4,
   type Experimental_VideoModelV4CallOptions as VideoModelV4CallOptions,
   type Experimental_VideoModelV4File as VideoModelV4File,
+  type Experimental_VideoModelV4OperationStartResult as VideoModelV4OperationStartResult,
+  type Experimental_VideoModelV4OperationStatusResult as VideoModelV4OperationStatusResult,
   type Experimental_VideoModelV4VideoData as VideoModelV4VideoData,
+  type JSONValue,
   type SharedV4ProviderMetadata,
   type SharedV4Warning,
 } from '@ai-sdk/provider';
@@ -11,6 +14,7 @@ import {
   combineHeaders,
   convertUint8ArrayToBase64,
   createJsonErrorResponseHandler,
+  createJsonResponseHandler,
   parseJsonEventStream,
   postJsonToApi,
   resolve,
@@ -38,22 +42,7 @@ export class GatewayVideoModel implements VideoModelV4 {
     return this.config.provider;
   }
 
-  async doGenerate({
-    prompt,
-    n,
-    aspectRatio,
-    resolution,
-    duration,
-    fps,
-    seed,
-    generateAudio,
-    image,
-    frameImages,
-    inputReferences,
-    providerOptions,
-    headers,
-    abortSignal,
-  }: VideoModelV4CallOptions): Promise<{
+  async doGenerate(options: VideoModelV4CallOptions): Promise<{
     videos: Array<VideoModelV4VideoData>;
     warnings: Array<SharedV4Warning>;
     providerMetadata?: SharedV4ProviderMetadata;
@@ -63,6 +52,7 @@ export class GatewayVideoModel implements VideoModelV4 {
       headers: Record<string, string> | undefined;
     };
   }> {
+    const { headers, abortSignal } = options;
     const resolvedHeaders = this.config.headers
       ? await resolve(this.config.headers)
       : undefined;
@@ -76,29 +66,7 @@ export class GatewayVideoModel implements VideoModelV4 {
           await resolve(this.config.o11yHeaders),
           { accept: 'text/event-stream' },
         ),
-        body: {
-          prompt,
-          n,
-          ...(aspectRatio && { aspectRatio }),
-          ...(resolution && { resolution }),
-          ...(duration && { duration }),
-          ...(fps && { fps }),
-          ...(seed && { seed }),
-          ...(generateAudio !== undefined && { generateAudio }),
-          ...(providerOptions && { providerOptions }),
-          ...(image && { image: maybeEncodeVideoFile(image) }),
-          ...(frameImages && {
-            frameImages: frameImages.map(frame => ({
-              ...frame,
-              image: maybeEncodeVideoFile(frame.image),
-            })),
-          }),
-          ...(inputReferences && {
-            inputReferences: inputReferences.map(reference =>
-              maybeEncodeVideoFile(reference),
-            ),
-          }),
-        },
+        body: this.buildRequestBody(options),
         successfulResponseHandler: async ({
           response,
           url,
@@ -186,8 +154,8 @@ export class GatewayVideoModel implements VideoModelV4 {
       return {
         videos: responseBody.videos,
         warnings: responseBody.warnings ?? [],
-        providerMetadata:
-          responseBody.providerMetadata as SharedV4ProviderMetadata,
+        providerMetadata: (responseBody.providerMetadata ??
+          undefined) as SharedV4ProviderMetadata,
         response: {
           timestamp: new Date(),
           modelId: this.modelId,
@@ -202,10 +170,209 @@ export class GatewayVideoModel implements VideoModelV4 {
     }
   }
 
+  // `handleWebhookOption` is intentionally NOT implemented. The Gateway's
+  // async video jobs are polling-first: it does not expose a provider->SDK
+  // webhook completion channel. If this method were present, `generateVideo`
+  // would forward a webhook URL and await a notification that never arrives.
+  // `doStart` still forwards the spec's `webhookUrl` — as the Gateway's
+  // `callbackUrl` wire field (its completion-webhook contract; unknown body
+  // keys are stripped server-side). Enabling webhooks later requires adding
+  // `handleWebhookOption` here plus handling the Gateway's HMAC-signed
+  // delivery format; the wire field is already the right one.
+
+  async doStart(
+    options: VideoModelV4CallOptions & {
+      webhookUrl?: string;
+    },
+  ): Promise<VideoModelV4OperationStartResult> {
+    const { headers, abortSignal, webhookUrl } = options;
+    const resolvedHeaders = this.config.headers
+      ? await resolve(this.config.headers)
+      : undefined;
+    try {
+      const { responseHeaders, value: responseBody } = await postJsonToApi({
+        url: this.getStartUrl(),
+        headers: combineHeaders(
+          resolvedHeaders,
+          headers ?? {},
+          this.getModelConfigHeaders(),
+          await resolve(this.config.o11yHeaders),
+        ),
+        body: {
+          ...this.buildRequestBody(options),
+          // The spec option is `webhookUrl`; the Gateway's wire contract for a
+          // completion webhook is `callbackUrl`.
+          ...(webhookUrl && { callbackUrl: webhookUrl }),
+        },
+        successfulResponseHandler: createJsonResponseHandler(
+          gatewayVideoStartResponseSchema,
+        ),
+        failedResponseHandler: createJsonErrorResponseHandler({
+          errorSchema: z.any(),
+          errorToMessage: data => data,
+        }),
+        ...(abortSignal && { abortSignal }),
+        fetch: this.config.fetch,
+      });
+
+      return {
+        operation: responseBody.operation as JSONValue,
+        warnings: responseBody.warnings ?? [],
+        providerMetadata: (responseBody.providerMetadata ??
+          undefined) as SharedV4ProviderMetadata,
+        response: {
+          timestamp: new Date(),
+          modelId: this.modelId,
+          headers: responseHeaders,
+        },
+      };
+    } catch (error) {
+      throw await asGatewayError(
+        error,
+        await parseAuthMethod(resolvedHeaders ?? {}),
+      );
+    }
+  }
+
+  async doStatus({
+    operation,
+    abortSignal,
+    headers,
+  }: {
+    operation: JSONValue;
+    abortSignal?: AbortSignal;
+    headers?: Record<string, string | undefined>;
+  }): Promise<VideoModelV4OperationStatusResult> {
+    const resolvedHeaders = this.config.headers
+      ? await resolve(this.config.headers)
+      : undefined;
+    try {
+      const { responseHeaders, value: responseBody } = await postJsonToApi({
+        url: this.getStatusUrl(),
+        headers: combineHeaders(
+          resolvedHeaders,
+          headers ?? {},
+          this.getModelConfigHeaders(),
+          await resolve(this.config.o11yHeaders),
+        ),
+        body: { operation },
+        successfulResponseHandler: createJsonResponseHandler(
+          gatewayVideoStatusResponseSchema,
+        ),
+        failedResponseHandler: createJsonErrorResponseHandler({
+          errorSchema: z.any(),
+          errorToMessage: data => data,
+        }),
+        ...(abortSignal && { abortSignal }),
+        fetch: this.config.fetch,
+      });
+
+      const response = {
+        timestamp: new Date(),
+        modelId: this.modelId,
+        headers: responseHeaders,
+      };
+
+      if (responseBody.status === 'completed') {
+        return {
+          status: 'completed',
+          videos: responseBody.videos,
+          warnings: responseBody.warnings ?? [],
+          providerMetadata: (responseBody.providerMetadata ??
+            undefined) as SharedV4ProviderMetadata,
+          response,
+        };
+      }
+
+      if (responseBody.status === 'error') {
+        return {
+          status: 'error',
+          error: responseBody.error,
+          providerMetadata: (responseBody.providerMetadata ??
+            undefined) as SharedV4ProviderMetadata,
+          response,
+        };
+      }
+
+      // The Gateway reports cooperative cancellation as its own terminal
+      // status; the v4 operation union has no cancelled state, so surface it
+      // as a terminal error rather than polling forever.
+      if (responseBody.status === 'cancelled') {
+        return {
+          status: 'error',
+          error: 'Video generation was cancelled.',
+          providerMetadata: (responseBody.providerMetadata ??
+            undefined) as SharedV4ProviderMetadata,
+          response,
+        };
+      }
+
+      return {
+        status: 'pending',
+        warnings: responseBody.warnings ?? [],
+        providerMetadata: (responseBody.providerMetadata ??
+          undefined) as SharedV4ProviderMetadata,
+        response,
+      };
+    } catch (error) {
+      throw await asGatewayError(
+        error,
+        await parseAuthMethod(resolvedHeaders ?? {}),
+      );
+    }
+  }
+
+  private buildRequestBody({
+    prompt,
+    n,
+    aspectRatio,
+    resolution,
+    duration,
+    fps,
+    seed,
+    generateAudio,
+    image,
+    frameImages,
+    inputReferences,
+    providerOptions,
+  }: VideoModelV4CallOptions) {
+    return {
+      prompt,
+      n,
+      ...(aspectRatio && { aspectRatio }),
+      ...(resolution && { resolution }),
+      ...(duration && { duration }),
+      ...(fps && { fps }),
+      ...(seed && { seed }),
+      ...(generateAudio !== undefined && { generateAudio }),
+      ...(providerOptions && { providerOptions }),
+      ...(image && { image: maybeEncodeVideoFile(image) }),
+      ...(frameImages && {
+        frameImages: frameImages.map(frame => ({
+          ...frame,
+          image: maybeEncodeVideoFile(frame.image),
+        })),
+      }),
+      ...(inputReferences && {
+        inputReferences: inputReferences.map(reference =>
+          maybeEncodeVideoFile(reference),
+        ),
+      }),
+    };
+  }
+
   private getUrl() {
     return `${this.config.baseURL}/video-model`;
   }
 
+  private getStartUrl() {
+    return `${this.config.baseURL}/video-model/start`;
+  }
+
+  private getStatusUrl() {
+    return `${this.config.baseURL}/video-model/status`;
+  }
+
   private getModelConfigHeaders() {
     return {
       'ai-video-model-specification-version': '4',
@@ -282,3 +449,40 @@ const gatewayVideoEventSchema = z.discriminatedUnion('type', [
     param: z.unknown().nullable(),
   }),
 ]);
+
+const gatewayVideoStartResponseSchema = z.object({
+  operation: z.unknown(),
+  warnings: z.array(gatewayVideoWarningSchema).nullish(),
+  providerMetadata: z.record(z.string(), providerMetadataEntrySchema).nullish(),
+});
+
+const gatewayVideoStatusResponseSchema = z.discriminatedUnion('status', [
+  z.object({
+    status: z.literal('pending'),
+    warnings: z.array(gatewayVideoWarningSchema).nullish(),
+    providerMetadata: z
+      .record(z.string(), providerMetadataEntrySchema)
+      .nullish(),
+  }),
+  z.object({
+    status: z.literal('completed'),
+    videos: z.array(gatewayVideoDataSchema),
+    warnings: z.array(gatewayVideoWarningSchema).nullish(),
+    providerMetadata: z
+      .record(z.string(), providerMetadataEntrySchema)
+      .nullish(),
+  }),
+  z.object({
+    status: z.literal('error'),
+    error: z.string(),
+    providerMetadata: z
+      .record(z.string(), providerMetadataEntrySchema)
+      .nullish(),
+  }),
+  z.object({
+    status: z.literal('cancelled'),
+    providerMetadata: z
+      .record(z.string(), providerMetadataEntrySchema)
+      .nullish(),
+  }),
+]);