feat (providers/gateway): include description and pricing info in model list (#7081)

## Background

Vercel AI Gateway customers would like programmatic access to pricing
info and brief description for the models in the model library.

## Summary

Add input/output token cost for the model entries produced by
`getAvailableModels` in the Gateway provider.

## Verification

Updated unit tests and tested manually with debug output in an example
script.

## Future Work

We aren't using the `specification` data in `GatewayLanguageModelEntry`
type. I looked at removing it as part of this change as dead code/data,
but as we've exported the specification type in the provider's
`index.ts`, removing it wholesale would be a breaking change. Leaving
further work here for the future.

Author: shaper

.changeset/gentle-hairs-study.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/gateway': patch
+---
+
+feat (providers/gateway): include description and pricing info in model list

packages/gateway/src/gateway-fetch-metadata.test.ts

@@ -28,13 +28,28 @@ describe('GatewayFetchMetadata', () => {
   const mockModelEntry = {
     id: 'model-1',
     name: 'Model One',
+    description: 'A test model',
+    pricing: {
+      input: '0.000001',
+      output: '0.000002',
+    },
     specification: {
-      specificationVersion: 'v2',
+      specificationVersion: 'v2' as const,
       provider: 'test-provider',
       modelId: 'model-1',
     },
   };
 
+  const mockModelEntryWithoutPricing = {
+    id: 'model-2',
+    name: 'Model Two',
+    specification: {
+      specificationVersion: 'v2' as const,
+      provider: 'test-provider',
+      modelId: 'model-2',
+    },
+  };
+
   const server = createTestServer({
     'https://api.example.com/*': {
       response: {
@@ -59,6 +74,77 @@ describe('GatewayFetchMetadata', () => {
       });
     });
 
+    it('should handle models with pricing information', async () => {
+      server.urls['https://api.example.com/*'].response = {
+        type: 'json-value',
+        body: {
+          models: [mockModelEntry],
+        },
+      };
+
+      const metadata = createBasicMetadataFetcher();
+      const result = await metadata.getAvailableModels();
+
+      expect(result.models[0]).toEqual(mockModelEntry);
+      expect(result.models[0].pricing).toEqual({
+        input: '0.000001',
+        output: '0.000002',
+      });
+    });
+
+    it('should handle models without pricing information', async () => {
+      server.urls['https://api.example.com/*'].response = {
+        type: 'json-value',
+        body: {
+          models: [mockModelEntryWithoutPricing],
+        },
+      };
+
+      const metadata = createBasicMetadataFetcher();
+      const result = await metadata.getAvailableModels();
+
+      expect(result.models[0]).toEqual(mockModelEntryWithoutPricing);
+      expect(result.models[0].pricing).toBeUndefined();
+    });
+
+    it('should handle mixed models with and without pricing', async () => {
+      server.urls['https://api.example.com/*'].response = {
+        type: 'json-value',
+        body: {
+          models: [mockModelEntry, mockModelEntryWithoutPricing],
+        },
+      };
+
+      const metadata = createBasicMetadataFetcher();
+      const result = await metadata.getAvailableModels();
+
+      expect(result.models).toHaveLength(2);
+      expect(result.models[0].pricing).toEqual({
+        input: '0.000001',
+        output: '0.000002',
+      });
+      expect(result.models[1].pricing).toBeUndefined();
+    });
+
+    it('should handle models with description', async () => {
+      const modelWithDescription = {
+        ...mockModelEntry,
+        description: 'A powerful language model',
+      };
+
+      server.urls['https://api.example.com/*'].response = {
+        type: 'json-value',
+        body: {
+          models: [modelWithDescription],
+        },
+      };
+
+      const metadata = createBasicMetadataFetcher();
+      const result = await metadata.getAvailableModels();
+
+      expect(result.models[0].description).toBe('A powerful language model');
+    });
+
     it('should pass headers correctly', async () => {
       const metadata = createBasicMetadataFetcher({
         headers: () => ({
@@ -159,6 +245,34 @@ describe('GatewayFetchMetadata', () => {
 
       await expect(metadata.getAvailableModels()).rejects.toThrow();
     });
+
+    it('should reject models with invalid pricing format', async () => {
+      server.urls['https://api.example.com/*'].response = {
+        type: 'json-value',
+        body: {
+          models: [
+            {
+              id: 'model-1',
+              name: 'Model One',
+              pricing: {
+                input: 123, // Should be string, not number
+                output: '0.000002',
+              },
+              specification: {
+                specificationVersion: 'v2',
+                provider: 'test-provider',
+                modelId: 'model-1',
+              },
+            },
+          ],
+        },
+      };
+
+      const metadata = createBasicMetadataFetcher();
+
+      await expect(metadata.getAvailableModels()).rejects.toThrow();
+    });
+
     it('should not double-wrap existing Gateway errors', async () => {
       // Create a Gateway error and verify it doesn't get wrapped
       const existingError = new GatewayAuthenticationError({
@@ -260,8 +374,13 @@ describe('GatewayFetchMetadata', () => {
       const customModelEntry = {
         id: 'custom-model-1',
         name: 'Custom Model One',
+        description: 'Custom model description',
+        pricing: {
+          input: '0.000005',
+          output: '0.000010',
+        },
         specification: {
-          specificationVersion: 'v2',
+          specificationVersion: 'v2' as const,
           provider: 'custom-provider',
           modelId: 'custom-model-1',
         },

packages/gateway/src/gateway-fetch-metadata.ts

@@ -46,9 +46,16 @@ const gatewayLanguageModelSpecificationSchema = z.object({
   modelId: z.string(),
 });
 
+const gatewayLanguageModelPricingSchema = z.object({
+  input: z.string(),
+  output: z.string(),
+});
+
 const gatewayLanguageModelEntrySchema = z.object({
   id: z.string(),
   name: z.string(),
+  description: z.string().nullish(),
+  pricing: gatewayLanguageModelPricingSchema.nullish(),
   specification: gatewayLanguageModelSpecificationSchema,
 });
 

packages/gateway/src/gateway-language-model.ts

@@ -149,18 +149,18 @@ export class GatewayLanguageModel implements LanguageModelV2 {
   }
 
   /**
-   * Encodes image parts in the prompt to base64. Mutates the passed options
-   * instance directly to avoid copying the image data.
+   * Encodes file parts in the prompt to base64. Mutates the passed options
+   * instance directly to avoid copying the file data.
    * @param options - The options to encode.
-   * @returns The options with the image parts encoded.
+   * @returns The options with the file parts encoded.
    */
   private maybeEncodeFileParts(options: LanguageModelV2CallOptions) {
     for (const message of options.prompt) {
       for (const part of message.content) {
         if (this.isFilePart(part)) {
           const filePart = part as LanguageModelV2FilePart;
-          // If the image part is a URL it will get cleanly converted to a string.
-          // If it's a binary image attachment we convert it to a data url.
+          // If the file part is a URL it will get cleanly converted to a string.
+          // If it's a binary file attachment we convert it to a data url.
           // In either case, server-side we should only ever see URLs as strings.
           if (filePart.data instanceof Uint8Array) {
             const buffer = Uint8Array.from(filePart.data);

packages/gateway/src/gateway-model-entry.ts

@@ -12,6 +12,25 @@ export interface GatewayLanguageModelEntry {
    */
   name: string;
 
+  /**
+   * Optional description of the model.
+   */
+  description?: string | null;
+
+  /**
+   * Optional pricing information for the model.
+   */
+  pricing?: {
+    /**
+     * Cost per input token in USD.
+     */
+    input: string;
+    /**
+     * Cost per output token in USD.
+     */
+    output: string;
+  } | null;
+
   /**
    * Additional AI SDK language model specifications for the model.
    */