feat (provider/openai): include more image generation response metadata (#10698)

## Background

The OpenAI Images API returns useful metadata about each request in the response. Callers may want to use this data for purposes like cost computation.

Reference: https://platform.openai.com/docs/pricing#image-generation


To compute the cost for an image generation a caller has to know:

- model
- image quality
- image dimensions

## Summary

Parse additional detail from OpenAI API response and include in provider response metadata.

## Manual Verification

Ran example scripts for openai.

## Checklist

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

Author: shaper

.changeset/heavy-suits-do.md

@@ -0,0 +1,5 @@
+---
+'@ai-sdk/openai': patch
+---
+
+feat (provider/openai): include more image generation response metadata

content/providers/01-ai-sdk-providers/03-openai.mdx

@@ -1479,7 +1479,20 @@ const { image, providerMetadata } = await generateImage({
 
 For more on `generateImage()` see [Image Generation](/docs/ai-sdk-core/image-generation).
 
-OpenAI's image models may return a revised prompt for each image. It can be access at `providerMetadata.openai.images[0]?.revisedPrompt`.
+OpenAI's image models return additional metadata in the response that can be
+accessed via `providerMetadata.openai`. The following OpenAI-specific metadata
+is available:
+
+- **images** _Array<object>_
+
+  Array of image-specific metadata. Each image object may contain:
+
+  - `revisedPrompt` _string_ - The revised prompt that was actually used to generate the image (OpenAI may modify your prompt for safety or clarity)
+  - `created` _number_ - The Unix timestamp (in seconds) of when the image was created
+  - `size` _string_ - The size of the generated image. One of `1024x1024`, `1024x1536`, or `1536x1024`
+  - `quality` _string_ - The quality of the generated image. One of `low`, `medium`, or `high`
+  - `background` _string_ - The background parameter used for the image generation. Either `transparent` or `opaque`
+  - `outputFormat` _string_ - The output format of the generated image. One of `png`, `webp`, or `jpeg`
 
 For more information on the available OpenAI image model options, see the [OpenAI API reference](https://platform.openai.com/docs/api-reference/images/create).
 

examples/ai-core/src/generate-image/google-vertex.ts

@@ -7,7 +7,7 @@ import 'dotenv/config';
 import { presentImages } from '../lib/present-image';
 
 async function main() {
-  const { image } = await generateImage({
+  const result = await generateImage({
     model: vertex.image('imagen-3.0-generate-002'),
     prompt: 'A burrito launched through a tunnel',
     aspectRatio: '1:1',
@@ -18,7 +18,12 @@ async function main() {
     },
   });
 
-  await presentImages([image]);
+  await presentImages(result.images);
+
+  console.log(
+    'Provider metadata:',
+    JSON.stringify(result.providerMetadata, null, 2),
+  );
 }
 
 main().catch(console.error);

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

@@ -4,22 +4,19 @@ import { presentImages } from '../lib/present-image';
 import 'dotenv/config';
 
 async function main() {
-  const prompt = 'Santa Claus driving a Cadillac';
+  const prompt = 'A blue cream Persian cat in Kyoto in the style of ukiyo-e';
   const result = await generateImage({
     model: openai.image('gpt-image-1-mini'),
     prompt,
+    n: 3,
   });
 
-  // @ts-expect-error
-  const revisedPrompt = result.providerMetadata.openai.images[0]?.revisedPrompt;
+  await presentImages(result.images);
 
-  console.log({
-    prompt,
-    revisedPrompt,
-    usage: result.usage,
-  });
-
-  await presentImages([result.image]);
+  console.log(
+    'Provider metadata:',
+    JSON.stringify(result.providerMetadata, null, 2),
+  );
 }
 
 main().catch(console.error);

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

@@ -6,12 +6,17 @@ import { z } from 'zod/v4';
 export const openaiImageResponseSchema = lazySchema(() =>
   zodSchema(
     z.object({
+      created: z.number().nullish(),
       data: z.array(
         z.object({
           b64_json: z.string(),
           revised_prompt: z.string().nullish(),
         }),
       ),
+      background: z.string().nullish(),
+      output_format: z.string().nullish(),
+      size: z.string().nullish(),
+      quality: z.string().nullish(),
       usage: z
         .object({
           input_tokens: z.number().nullish(),

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

@@ -266,7 +266,15 @@ describe('doGenerate', () => {
     expect(result.warnings).toStrictEqual([]);
     expect(result.providerMetadata).toStrictEqual({
       openai: {
-        images: [null],
+        images: [
+          {
+            created: 1733837122,
+            size: undefined,
+            quality: undefined,
+            background: undefined,
+            outputFormat: undefined,
+          },
+        ],
       },
     });
   });
@@ -306,8 +314,19 @@ describe('doGenerate', () => {
           {
             revisedPrompt:
               'A charming visual illustration of a baby sea otter swimming joyously.',
+            created: 1733837122,
+            size: undefined,
+            quality: undefined,
+            background: undefined,
+            outputFormat: undefined,
+          },
+          {
+            created: 1733837122,
+            size: undefined,
+            quality: undefined,
+            background: undefined,
+            outputFormat: undefined,
           },
-          null,
         ],
       },
     });

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

@@ -105,13 +105,16 @@ export class OpenAIImageModel implements ImageModelV3 {
       },
       providerMetadata: {
         openai: {
-          images: response.data.map(item =>
-            item.revised_prompt
-              ? {
-                  revisedPrompt: item.revised_prompt,
-                }
-              : null,
-          ),
+          images: response.data.map(item => ({
+            ...(item.revised_prompt
+              ? { revisedPrompt: item.revised_prompt }
+              : {}),
+            created: response.created ?? undefined,
+            size: response.size ?? undefined,
+            quality: response.quality ?? undefined,
+            background: response.background ?? undefined,
+            outputFormat: response.output_format ?? undefined,
+          })),
         },
       },
     };