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

This is an automated backport of #10698 to the release-v5.0 branch. FYI
@shaper

---------

Co-authored-by: Walter Korman <[email protected]>

Author: vercel-ai-sdk[bot]

.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

@@ -1408,7 +1408,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,21 +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,
-  });
-
-  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,30 @@ import { z } from 'zod/v4';
 export const openaiImageResponseSchema = lazyValidator(() =>
   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(),
+          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

@@ -265,7 +265,11 @@ describe('doGenerate', () => {
     expect(result.warnings).toStrictEqual([]);
     expect(result.providerMetadata).toStrictEqual({
       openai: {
-        images: [null],
+        images: [
+          {
+            created: 1733837122,
+          },
+        ],
       },
     });
   });
@@ -305,8 +309,176 @@ describe('doGenerate', () => {
           {
             revisedPrompt:
               'A charming visual illustration of a baby sea otter swimming joyously.',
+            created: 1733837122,
+          },
+          {
+            created: 1733837122,
+          },
+        ],
+      },
+    });
+  });
+
+  it('should include all metadata fields when present in response', async () => {
+    server.urls['https://api.openai.com/v1/images/generations'].response = {
+      type: 'json-value',
+      body: {
+        created: 1733837122,
+        size: '1024x1024',
+        quality: 'hd',
+        background: 'transparent',
+        output_format: 'png',
+        data: [
+          {
+            revised_prompt: 'A detailed illustration of a cat',
+            b64_json: 'base64-image-1',
+          },
+        ],
+      },
+    };
+
+    const result = await model.doGenerate({
+      prompt,
+      n: 1,
+      size: '1024x1024',
+      aspectRatio: undefined,
+      seed: undefined,
+      providerOptions: {},
+    });
+
+    expect(result.providerMetadata).toStrictEqual({
+      openai: {
+        images: [
+          {
+            revisedPrompt: 'A detailed illustration of a cat',
+            created: 1733837122,
+            size: '1024x1024',
+            quality: 'hd',
+            background: 'transparent',
+            outputFormat: 'png',
+          },
+        ],
+      },
+    });
+  });
+
+  it('should handle response with no metadata fields', async () => {
+    server.urls['https://api.openai.com/v1/images/generations'].response = {
+      type: 'json-value',
+      body: {
+        data: [
+          {
+            b64_json: 'base64-image-1',
+          },
+        ],
+      },
+    };
+
+    const result = await model.doGenerate({
+      prompt,
+      n: 1,
+      size: undefined,
+      aspectRatio: undefined,
+      seed: undefined,
+      providerOptions: {},
+    });
+
+    expect(result.providerMetadata).toStrictEqual({
+      openai: {
+        images: [{}],
+      },
+    });
+  });
+
+  it('should handle multiple images with mixed metadata', async () => {
+    server.urls['https://api.openai.com/v1/images/generations'].response = {
+      type: 'json-value',
+      body: {
+        created: 1733837122,
+        size: '1024x1024',
+        quality: 'hd',
+        data: [
+          {
+            revised_prompt: 'First image prompt',
+            b64_json: 'base64-image-1',
+          },
+          {
+            b64_json: 'base64-image-2',
+          },
+          {
+            revised_prompt: 'Third image prompt',
+            b64_json: 'base64-image-3',
+          },
+        ],
+      },
+    };
+
+    const result = await model.doGenerate({
+      prompt,
+      n: 3,
+      size: '1024x1024',
+      aspectRatio: undefined,
+      seed: undefined,
+      providerOptions: {},
+    });
+
+    expect(result.providerMetadata).toStrictEqual({
+      openai: {
+        images: [
+          {
+            revisedPrompt: 'First image prompt',
+            created: 1733837122,
+            size: '1024x1024',
+            quality: 'hd',
+          },
+          {
+            created: 1733837122,
+            size: '1024x1024',
+            quality: 'hd',
+          },
+          {
+            revisedPrompt: 'Third image prompt',
+            created: 1733837122,
+            size: '1024x1024',
+            quality: 'hd',
+          },
+        ],
+      },
+    });
+  });
+
+  it('should handle jpeg output format', async () => {
+    server.urls['https://api.openai.com/v1/images/generations'].response = {
+      type: 'json-value',
+      body: {
+        created: 1733837122,
+        output_format: 'jpeg',
+        quality: 'standard',
+        data: [
+          {
+            b64_json: 'base64-image-1',
+          },
+        ],
+      },
+    };
+
+    const result = await model.doGenerate({
+      prompt,
+      n: 1,
+      size: undefined,
+      aspectRatio: undefined,
+      seed: undefined,
+      providerOptions: {},
+    });
+
+    expect(result.providerMetadata).toStrictEqual({
+      openai: {
+        images: [
+          {
+            created: 1733837122,
+            quality: 'standard',
+            outputFormat: 'jpeg',
           },
-          null,
         ],
       },
     });

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

@@ -97,13 +97,20 @@ export class OpenAIImageModel implements ImageModelV2 {
       },
       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 }
+              : {}),
+            ...(response.created != null ? { created: response.created } : {}),
+            ...(response.size != null ? { size: response.size } : {}),
+            ...(response.quality != null ? { quality: response.quality } : {}),
+            ...(response.background != null
+              ? { background: response.background }
+              : {}),
+            ...(response.output_format != null
+              ? { outputFormat: response.output_format }
+              : {}),
+          })),
         },
       },
     };