@ai-sdk/xai 4.0.33 → 4.0.35

package/docs/01-xai.mdx

@@ -369,6 +369,47 @@ const { text } = await generateText({
 });
 ```
 
+### Image Generation Tool
+
+The image generation tool lets the model create and edit images with Grok Imagine as part of a conversation. The model decides when to call the tool, writes the image prompt, and returns the finished image alongside its text response:
+
+```ts
+import { xai } from '@ai-sdk/xai';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: xai.responses('grok-4.5'),
+  prompt:
+    'Generate an image of a corgi surfing a big wave, in the style of a Japanese woodblock print',
+  tools: {
+    image_generation: xai.tools.imageGeneration(),
+  },
+});
+
+for (const toolResult of result.staticToolResults) {
+  if (toolResult.toolName === 'image_generation') {
+    const base64Image = toolResult.output.result;
+  }
+}
+```
+
+The tool result also contains the prompt that the model wrote for the image model, which is useful for understanding and debugging what was generated.
+
+#### Image Generation Parameters
+
+- **action** _'auto' | 'generate' | 'edit'_
+
+  Restricts what the tool can do. Defaults to `'auto'`.
+  - `'auto'`: the model can generate and edit images.
+  - `'generate'`: text-to-image generation only.
+  - `'edit'`: image editing only (edits images already in the conversation, including images the model generated earlier).
+
+<Note>
+  The tool takes no size or format parameters; the model picks an aspect ratio
+  for each call. To control it, ask in your prompt (e.g. "in a 9:16 vertical
+  aspect ratio").
+</Note>
+
 ### MCP Server Tool
 
 The MCP server tool enables the model to connect to remote [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers and use their tools:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "4.0.33",
+  "version": "4.0.35",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.7",
-    "@ai-sdk/provider-utils": "5.0.25"
+    "@ai-sdk/provider-utils": "5.0.27"
   },
   "devDependencies": {
     "@types/node": "22.19.19",

package/src/index.ts

@@ -30,6 +30,7 @@ export { XaiRealtimeModel as Experimental_XaiRealtimeModel } from './realtime/xa
 export type { XaiRealtimeModelConfig as Experimental_XaiRealtimeModelConfig } from './realtime/xai-realtime-model';
 export {
   codeExecution,
+  imageGeneration,
   mcpServer,
   viewImage,
   viewXVideo,

package/src/responses/xai-responses-api.ts

@@ -109,6 +109,10 @@ export type XaiResponsesTool =
   | { type: 'code_interpreter' }
   | { type: 'view_image' }
   | { type: 'view_x_video' }
+  | {
+      type: 'image_generation';
+      action?: 'auto' | 'generate' | 'edit';
+    }
   | {
       type: 'file_search';
       vector_store_ids?: string[];
@@ -215,6 +219,13 @@ const outputItemSchema = z.discriminatedUnion('type', [
       )
       .nullish(),
   }),
+  z.object({
+    type: z.literal('image_generation_call'),
+    id: z.string(),
+    status: z.string(),
+    prompt: z.string().nullish(),
+    result: z.string().nullish(),
+  }),
   z.object({
     type: z.literal('custom_tool_call'),
     ...toolCallSchema.shape,
@@ -423,6 +434,21 @@ export const xaiResponsesChunkSchema = z.union([
     item_id: z.string(),
     output_index: z.number(),
   }),
+  z.object({
+    type: z.literal('response.image_generation_call.in_progress'),
+    item_id: z.string(),
+    output_index: z.number(),
+  }),
+  z.object({
+    type: z.literal('response.image_generation_call.generating'),
+    item_id: z.string(),
+    output_index: z.number(),
+  }),
+  z.object({
+    type: z.literal('response.image_generation_call.completed'),
+    item_id: z.string(),
+    output_index: z.number(),
+  }),
   z.object({
     type: z.literal('response.code_execution_call.in_progress'),
     item_id: z.string(),

package/src/responses/xai-responses-language-model.ts

@@ -149,6 +149,10 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
       tool => tool.type === 'provider' && tool.id === 'xai.file_search',
     )?.name;
 
+    const imageGenerationToolName = tools?.find(
+      tool => tool.type === 'provider' && tool.id === 'xai.image_generation',
+    )?.name;
+
     const { input, inputWarnings } = await convertToXaiResponsesInput({
       prompt,
       store: options.store ?? true,
@@ -269,6 +273,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
       codeExecutionToolName,
       mcpToolName,
       fileSearchToolName,
+      imageGenerationToolName,
     };
   }
 
@@ -283,6 +288,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
       codeExecutionToolName,
       mcpToolName,
       fileSearchToolName,
+      imageGenerationToolName,
     } = await this.getArgs(options);
 
     const {
@@ -347,6 +353,40 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
         continue;
       }
 
+      if (part.type === 'image_generation_call') {
+        const toolName = imageGenerationToolName ?? 'image_generation';
+
+        content.push({
+          type: 'tool-call',
+          toolCallId: part.id,
+          toolName,
+          input: '{}',
+          providerExecuted: true,
+        });
+
+        if (part.result != null) {
+          content.push({
+            type: 'tool-result',
+            toolCallId: part.id,
+            toolName,
+            result: {
+              result: part.result,
+              ...(part.prompt != null && { prompt: part.prompt }),
+            },
+          });
+        } else {
+          content.push({
+            type: 'tool-result',
+            toolCallId: part.id,
+            toolName,
+            isError: true,
+            result: `Image generation failed (status: ${part.status}).`,
+          });
+        }
+
+        continue;
+      }
+
       if (
         part.type === 'web_search_call' ||
         part.type === 'x_search_call' ||
@@ -514,6 +554,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
       codeExecutionToolName,
       mcpToolName,
       fileSearchToolName,
+      imageGenerationToolName,
     } = await this.getArgs(options);
     const body = {
       ...args,
@@ -801,6 +842,45 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
               return;
             }
 
+            if (
+              event.type === 'response.image_generation_call.in_progress' ||
+              event.type === 'response.image_generation_call.generating' ||
+              event.type === 'response.image_generation_call.completed'
+            ) {
+              if (!seenToolCalls.has(event.item_id)) {
+                seenToolCalls.add(event.item_id);
+
+                const toolName = imageGenerationToolName ?? 'image_generation';
+
+                controller.enqueue({
+                  type: 'tool-input-start',
+                  id: event.item_id,
+                  toolName,
+                });
+
+                controller.enqueue({
+                  type: 'tool-input-delta',
+                  id: event.item_id,
+                  delta: '{}',
+                });
+
+                controller.enqueue({
+                  type: 'tool-input-end',
+                  id: event.item_id,
+                });
+
+                controller.enqueue({
+                  type: 'tool-call',
+                  toolCallId: event.item_id,
+                  toolName,
+                  input: '{}',
+                  providerExecuted: true,
+                });
+              }
+
+              return;
+            }
+
             if (
               event.type === 'response.output_item.added' ||
               event.type === 'response.output_item.done'
@@ -895,6 +975,63 @@ export class XaiResponsesLanguageModel implements LanguageModelV4 {
                 return;
               }
 
+              if (part.type === 'image_generation_call') {
+                const toolName = imageGenerationToolName ?? 'image_generation';
+
+                if (!seenToolCalls.has(part.id)) {
+                  seenToolCalls.add(part.id);
+
+                  controller.enqueue({
+                    type: 'tool-input-start',
+                    id: part.id,
+                    toolName,
+                  });
+
+                  controller.enqueue({
+                    type: 'tool-input-delta',
+                    id: part.id,
+                    delta: '{}',
+                  });
+
+                  controller.enqueue({
+                    type: 'tool-input-end',
+                    id: part.id,
+                  });
+
+                  controller.enqueue({
+                    type: 'tool-call',
+                    toolCallId: part.id,
+                    toolName,
+                    input: '{}',
+                    providerExecuted: true,
+                  });
+                }
+
+                if (event.type === 'response.output_item.done') {
+                  if (part.result != null) {
+                    controller.enqueue({
+                      type: 'tool-result',
+                      toolCallId: part.id,
+                      toolName,
+                      result: {
+                        result: part.result,
+                        ...(part.prompt != null && { prompt: part.prompt }),
+                      },
+                    });
+                  } else {
+                    controller.enqueue({
+                      type: 'tool-result',
+                      toolCallId: part.id,
+                      toolName,
+                      isError: true,
+                      result: `Image generation failed (status: ${part.status}).`,
+                    });
+                  }
+                }
+
+                return;
+              }
+
               if (
                 part.type === 'web_search_call' ||
                 part.type === 'x_search_call' ||

package/src/responses/xai-responses-prepare-tools.ts

@@ -6,6 +6,7 @@ import {
 import { validateTypes } from '@ai-sdk/provider-utils';
 import { removeAdditionalPropertiesFalse } from '../remove-additional-properties';
 import { fileSearchArgsSchema } from '../tool/file-search';
+import { imageGenerationArgsSchema } from '../tool/image-generation';
 import { mcpServerArgsSchema } from '../tool/mcp-server';
 import { webSearchArgsSchema } from '../tool/web-search';
 import { xSearchArgsSchema } from '../tool/x-search';
@@ -99,6 +100,19 @@ export async function prepareResponsesTools({
           break;
         }
 
+        case 'xai.image_generation': {
+          const args = await validateTypes({
+            value: tool.args,
+            schema: imageGenerationArgsSchema,
+          });
+
+          xaiTools.push({
+            type: 'image_generation',
+            action: args.action,
+          });
+          break;
+        }
+
         case 'xai.file_search': {
           const args = await validateTypes({
             value: tool.args,

package/src/tool/image-generation.ts

@@ -0,0 +1,62 @@
+import {
+  createProviderExecutedToolFactory,
+  lazySchema,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+/**
+ * Schema for image generation tool arguments.
+ * @see https://docs.x.ai/developers/tools/overview
+ */
+export const imageGenerationArgsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      action: z.enum(['auto', 'generate', 'edit']).optional(),
+    }),
+  ),
+);
+
+const imageGenerationInputSchema = lazySchema(() => zodSchema(z.object({})));
+
+const imageGenerationOutputSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      result: z.string(),
+      prompt: z.string().optional(),
+    }),
+  ),
+);
+
+const imageGenerationToolFactory = createProviderExecutedToolFactory<
+  {},
+  {
+    /**
+     * The generated image encoded in base64.
+     */
+    result: string;
+
+    /**
+     * The prompt that the model wrote for the image model.
+     */
+    prompt?: string;
+  },
+  {
+    /**
+     * Restricts what the tool can do. Defaults to 'auto'.
+     *
+     * - 'auto': the model can generate and edit images.
+     * - 'generate': text-to-image generation only.
+     * - 'edit': image editing only.
+     */
+    action?: 'auto' | 'generate' | 'edit';
+  }
+>({
+  id: 'xai.image_generation',
+  inputSchema: imageGenerationInputSchema,
+  outputSchema: imageGenerationOutputSchema,
+});
+
+export const imageGeneration = (
+  args: Parameters<typeof imageGenerationToolFactory>[0] = {},
+) => imageGenerationToolFactory(args);

package/src/tool/index.ts

@@ -1,5 +1,6 @@
 import { codeExecution } from './code-execution';
 import { fileSearch } from './file-search';
+import { imageGeneration } from './image-generation';
 import { mcpServer } from './mcp-server';
 import { viewImage } from './view-image';
 import { viewXVideo } from './view-x-video';
@@ -9,6 +10,7 @@ import { xSearch } from './x-search';
 export {
   codeExecution,
   fileSearch,
+  imageGeneration,
   mcpServer,
   viewImage,
   viewXVideo,
@@ -19,6 +21,7 @@ export {
 export const xaiTools = {
   codeExecution,
   fileSearch,
+  imageGeneration,
   mcpServer,
   viewImage,
   viewXVideo,