feat(ai, openai): expose usage tokens for 'generateImage' function (#10128)

## Background

`experimental_generateImage` doesn't expose the token usage information
returned by providers. this PR introduces token usage for OpenAI
provider

We also update the ImageProvider spec so as to allow for usage tokens

See #8358 

## Summary

- create new type `ImageModelUsage`
- update openai image api response schema
- map responses to appropriate vars [`inputTokens`, `outputTokens`,
`totalTokens`]

## Manual Verification

- updated unit tests
- updated example in `examples/ai-core/generate-image/openai.ts`
- [ ] test with e2e UI example

## Checklist

- [x] Tests have been added / updated (for bug fixes / features)
- [ ] Documentation has been added / updated (for bug fixes / features)
- [ ] A _patch_ changeset for relevant packages has been added (for bug
fixes / features - run `pnpm changeset` in the project root)

## Future Work

Will need support for other providers for which we support image
generation

#10150

## Related Issues

Fixes #8358

Author: aayush-kapoor

.changeset/plenty-forks-double.md

@@ -0,0 +1,7 @@
+---
+'@ai-sdk/provider': patch
+'@ai-sdk/openai': patch
+'ai': patch
+---
+
+feat: expose usage tokens for 'generateImage' function

examples/ai-core/src/generate-image/openai.ts

@@ -16,6 +16,7 @@ async function main() {
   console.log({
     prompt,
     revisedPrompt,
+    usage: result.usage,
   });
 
   await presentImages([result.image]);

packages/ai/src/generate-image/generate-image-result.ts

@@ -4,6 +4,7 @@ import {
   ImageModelProviderMetadata,
 } from '../types/image-model';
 import { ImageModelResponseMetadata } from '../types/image-model-response-metadata';
+import { ImageModelUsage } from '../types/usage';
 
 /**
 The result of a `generateImage` call.
@@ -35,4 +36,9 @@ Response metadata from the provider. There may be multiple responses if we made
    * results that can be fully encapsulated in the provider.
    */
   readonly providerMetadata: ImageModelProviderMetadata;
+
+  /**
+  Combined token usage across all underlying provider calls for this image generation.
+   */
+  readonly usage: ImageModelUsage;
 }

packages/ai/src/generate-image/generate-image.test.ts

@@ -651,4 +651,86 @@ describe('generateImage', () => {
       },
     });
   });
+
+  it('should expose empty usage when provider does not report usage', async () => {
+    const result = await generateImage({
+      model: new MockImageModelV3({
+        doGenerate: async () =>
+          createMockResponse({
+            images: [pngBase64],
+          }),
+      }),
+      prompt,
+    });
+
+    expect(result.usage).toStrictEqual({
+      inputTokens: undefined,
+      outputTokens: undefined,
+      totalTokens: undefined,
+    });
+  });
+
+  it('should aggregate usage across multiple provider calls', async () => {
+    let callCount = 0;
+
+    const result = await generateImage({
+      model: new MockImageModelV3({
+        maxImagesPerCall: 1,
+        doGenerate: async () => {
+          switch (callCount++) {
+            case 0:
+              return {
+                images: [pngBase64],
+                warnings: [],
+                providerMetadata: {
+                  testProvider: { images: [null] },
+                },
+                response: {
+                  timestamp: new Date(),
+                  modelId: 'mock-model-id',
+                  headers: {},
+                },
+                usage: {
+                  inputTokens: 10,
+                  outputTokens: 0,
+                  totalTokens: 10,
+                },
+              };
+            case 1:
+              return {
+                images: [jpegBase64],
+                warnings: [],
+                providerMetadata: {
+                  testProvider: { images: [null] },
+                },
+                response: {
+                  timestamp: new Date(),
+                  modelId: 'mock-model-id',
+                  headers: {},
+                },
+                usage: {
+                  inputTokens: 5,
+                  outputTokens: 0,
+                  totalTokens: 5,
+                },
+              };
+            default:
+              throw new Error('Unexpected call');
+          }
+        },
+      }),
+      prompt,
+      n: 2,
+    });
+
+    expect(result.images.map(image => image.base64)).toStrictEqual([
+      pngBase64,
+      jpegBase64,
+    ]);
+    expect(result.usage).toStrictEqual({
+      inputTokens: 15,
+      outputTokens: 0,
+      totalTokens: 15,
+    });
+  });
 });

packages/ai/src/generate-image/generate-image.ts

@@ -16,6 +16,7 @@ import { ImageModelResponseMetadata } from '../types/image-model-response-metada
 import { GenerateImageResult } from './generate-image-result';
 import { logWarnings } from '../logger/log-warnings';
 import { VERSION } from '../version';
+import { addImageModelUsage, ImageModelUsage } from '../types/usage';
 
 /**
 Generates images using an image model.
@@ -172,6 +173,11 @@ Only applicable for HTTP-based providers.
   const warnings: Array<ImageGenerationWarning> = [];
   const responses: Array<ImageModelResponseMetadata> = [];
   const providerMetadata: ImageModelV3ProviderMetadata = {};
+  let totalUsage: ImageModelUsage = {
+    inputTokens: undefined,
+    outputTokens: undefined,
+    totalTokens: undefined,
+  };
   for (const result of results) {
     images.push(
       ...result.images.map(
@@ -188,6 +194,10 @@ Only applicable for HTTP-based providers.
     );
     warnings.push(...result.warnings);
 
+    if (result.usage != null) {
+      totalUsage = addImageModelUsage(totalUsage, result.usage);
+    }
+
     if (result.providerMetadata) {
       for (const [providerName, metadata] of Object.entries<{
         images: unknown;
@@ -213,6 +223,7 @@ Only applicable for HTTP-based providers.
     warnings,
     responses,
     providerMetadata,
+    usage: totalUsage,
   });
 }
 
@@ -221,17 +232,20 @@ class DefaultGenerateImageResult implements GenerateImageResult {
   readonly warnings: Array<ImageGenerationWarning>;
   readonly responses: Array<ImageModelResponseMetadata>;
   readonly providerMetadata: ImageModelV3ProviderMetadata;
+  readonly usage: ImageModelUsage;
 
   constructor(options: {
     images: Array<GeneratedFile>;
     warnings: Array<ImageGenerationWarning>;
     responses: Array<ImageModelResponseMetadata>;
     providerMetadata: ImageModelV3ProviderMetadata;
+    usage: ImageModelUsage;
   }) {
     this.images = options.images;
     this.warnings = options.warnings;
     this.responses = options.responses;
     this.providerMetadata = options.providerMetadata;
+    this.usage = options.usage;
   }
 
   get image() {

packages/ai/src/types/index.ts

@@ -27,4 +27,8 @@ export type {
   TranscriptionWarning,
 } from './transcription-model';
 export type { TranscriptionModelResponseMetadata } from './transcription-model-response-metadata';
-export type { EmbeddingModelUsage, LanguageModelUsage } from './usage';
+export type {
+  EmbeddingModelUsage,
+  LanguageModelUsage,
+  ImageModelUsage,
+} from './usage';

packages/ai/src/types/usage.ts

@@ -1,4 +1,5 @@
 import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import { ImageModelV3Usage } from '@ai-sdk/provider';
 
 /**
 Represents the number of tokens used in a prompt and completion.
@@ -43,3 +44,19 @@ function addTokenCounts(
     ? undefined
     : (tokenCount1 ?? 0) + (tokenCount2 ?? 0);
 }
+
+/**
+Usage information for an image model call.
+ */
+export type ImageModelUsage = ImageModelV3Usage;
+
+export function addImageModelUsage(
+  usage1: ImageModelUsage,
+  usage2: ImageModelUsage,
+): ImageModelUsage {
+  return {
+    inputTokens: addTokenCounts(usage1.inputTokens, usage2.inputTokens),
+    outputTokens: addTokenCounts(usage1.outputTokens, usage2.outputTokens),
+    totalTokens: addTokenCounts(usage1.totalTokens, usage2.totalTokens),
+  };
+}

packages/openai/src/image/openai-image-api.ts

@@ -12,6 +12,19 @@ export const openaiImageResponseSchema = lazySchema(() =>
           revised_prompt: z.string().nullish(),
         }),
       ),
+      usage: z
+        .object({
+          input_tokens: z.number().nullish(),
+          output_tokens: z.number().nullish(),
+          total_tokens: z.number().nullish(),
+          input_tokens_details: z
+            .object({
+              image_tokens: z.number().nullish(),
+              text_tokens: z.number().nullish(),
+            })
+            .nullish(),
+        })
+        .nullish(),
     }),
   ),
 );

packages/openai/src/image/openai-image-model.test.ts

@@ -311,4 +311,42 @@ describe('doGenerate', () => {
       },
     });
   });
+
+  it('should map OpenAI usage to usage', async () => {
+    server.urls['https://api.openai.com/v1/images/generations'].response = {
+      type: 'json-value',
+      body: {
+        created: 1733837122,
+        data: [
+          {
+            b64_json: 'base64-image-1',
+          },
+        ],
+        usage: {
+          input_tokens: 12,
+          output_tokens: 0,
+          total_tokens: 12,
+          input_tokens_details: {
+            image_tokens: 7,
+            text_tokens: 5,
+          },
+        },
+      },
+    };
+
+    const result = await provider.image('gpt-image-1').doGenerate({
+      prompt,
+      n: 1,
+      size: '1024x1024',
+      aspectRatio: undefined,
+      seed: undefined,
+      providerOptions: {},
+    });
+
+    expect(result.usage).toStrictEqual({
+      inputTokens: 12,
+      outputTokens: 0,
+      totalTokens: 12,
+    });
+  });
 });

packages/openai/src/image/openai-image-model.ts

@@ -90,6 +90,14 @@ export class OpenAIImageModel implements ImageModelV3 {
     return {
       images: response.data.map(item => item.b64_json),
       warnings,
+      usage:
+        response.usage != null
+          ? {
+              inputTokens: response.usage.input_tokens ?? undefined,
+              outputTokens: response.usage.output_tokens ?? undefined,
+              totalTokens: response.usage.total_tokens ?? undefined,
+            }
+          : undefined,
       response: {
         timestamp: currentDate,
         modelId: this.modelId,