@tanstack/ai-grok 0.11.3 → 0.12.1

package/dist/esm/adapters/image.d.ts

@@ -2,7 +2,7 @@ import { default as OpenAI } from 'openai';
 import { BaseImageAdapter } from '@tanstack/ai/adapters';
 import { ImageGenerationOptions, ImageGenerationResult } from '@tanstack/ai';
 import { GrokImageModel } from '../model-meta.js';
-import { GrokImageModelProviderOptionsByName, GrokImageModelSizeByName, GrokImageProviderOptions } from '../image/image-provider-options.js';
+import { GrokImageModelInputModalitiesByName, GrokImageModelProviderOptionsByName, GrokImageModelSizeByName, GrokImageProviderOptions } from '../image/image-provider-options.js';
 import { GrokClientConfig } from '../utils.js';
 /**
  * Configuration for Grok image adapter
@@ -13,19 +13,34 @@ export interface GrokImageConfig extends GrokClientConfig {
  * Grok Image Generation Adapter
  *
  * Tree-shakeable adapter for Grok image generation functionality.
- * Supports grok-2-image-1212 model.
+ * Supports the legacy grok-2-image-1212 model (text-to-image via the
+ * OpenAI-compat endpoint) and the grok-imagine image models, which also
+ * accept image prompt parts for image-conditioned generation via xAI's
+ * `/v1/images/edits` endpoint (up to 3 source images).
  *
  * Features:
  * - Model-specific type-safe provider options
- * - Size validation per model
+ * - Size / aspect-ratio validation per model
  * - Number of images validation
  */
-export declare class GrokImageAdapter<TModel extends GrokImageModel> extends BaseImageAdapter<TModel, GrokImageProviderOptions, GrokImageModelProviderOptionsByName, GrokImageModelSizeByName> {
+export declare class GrokImageAdapter<TModel extends GrokImageModel> extends BaseImageAdapter<TModel, GrokImageProviderOptions, GrokImageModelProviderOptionsByName, GrokImageModelSizeByName, GrokImageModelInputModalitiesByName> {
     readonly kind: "image";
     readonly name: "grok";
     protected client: OpenAI;
+    private readonly clientConfig;
     constructor(config: GrokImageConfig, model: TModel);
     generateImages(options: ImageGenerationOptions<GrokImageProviderOptions>): Promise<ImageGenerationResult>;
+    /**
+     * Image-conditioned generation via xAI's Imagine API.
+     *
+     * The `/v1/images/edits` endpoint takes `application/json` (the OpenAI
+     * SDK's `images.edit()` sends `multipart/form-data`, which xAI rejects),
+     * so this path issues the request directly. One input is sent as
+     * `image: { url }`; multiple inputs (up to 3) as `images: [{ url }, ...]`,
+     * addressed by xAI in the order they are sent. The prompt text is sent
+     * verbatim — no referencing markers are injected.
+     */
+    private editImages;
 }
 /**
  * Creates a Grok image adapter with explicit API key.

package/dist/esm/adapters/image.js

@@ -1,29 +1,63 @@
 import OpenAI from "openai";
+import { resolveMediaPrompt } from "@tanstack/ai";
 import { BaseImageAdapter } from "@tanstack/ai/adapters";
 import { toRunErrorPayload } from "@tanstack/ai/adapter-internals";
 import { buildImagesUsage } from "@tanstack/openai-base";
 import { generateId } from "@tanstack/ai-utils";
 import { withGrokDefaults, getGrokApiKeyFromEnv } from "../utils/client.js";
-import { validatePrompt, validateImageSize, validateNumberOfImages } from "../image/image-provider-options.js";
+import { isGrokImagineImageModel, validatePrompt, validateImageSize, validateNumberOfImages, parseGrokImagineSize } from "../image/image-provider-options.js";
+const MAX_EDIT_IMAGES = 3;
+function imagineSizeParams(size) {
+  if (!size) return {};
+  const parsed = parseGrokImagineSize(size);
+  if (!parsed) return {};
+  return {
+    aspect_ratio: parsed.aspectRatio,
+    ...parsed.resolution !== void 0 && { resolution: parsed.resolution }
+  };
+}
+function imagePartToUrl(part) {
+  if (part.source.type === "url") return part.source.value;
+  return `data:${part.source.mimeType};base64,${part.source.value}`;
+}
 class GrokImageAdapter extends BaseImageAdapter {
   kind = "image";
   name = "grok";
   client;
+  clientConfig;
   constructor(config, model) {
     super(model, {});
-    this.client = new OpenAI(withGrokDefaults(config));
+    this.clientConfig = withGrokDefaults(config);
+    this.client = new OpenAI(this.clientConfig);
   }
   async generateImages(options) {
-    const { model, prompt, numberOfImages, size, modelOptions } = options;
+    const { model, numberOfImages, size, modelOptions } = options;
+    const resolved = resolveMediaPrompt(options.prompt);
+    const prompt = resolved.text;
+    if (resolved.videos.length > 0 || resolved.audios.length > 0) {
+      throw new Error(
+        `grok.generateImages does not support video / audio prompt parts on model ${model}.`
+      );
+    }
+    if (resolved.images.length > 0) {
+      if (!isGrokImagineImageModel(model)) {
+        throw new Error(
+          `grok: model "${model}" does not support image prompt parts. Image-conditioned generation requires an Imagine API model ('grok-imagine-image' or 'grok-imagine-image-quality').`
+        );
+      }
+      return await this.editImages(options, resolved);
+    }
     validatePrompt({ prompt });
     validateImageSize(model, size);
     validateNumberOfImages(model, numberOfImages);
-    const resolvedSize = size;
+    const isImagine = isGrokImagineImageModel(model);
     const request = {
       model,
       prompt,
       n: numberOfImages ?? 1,
-      ...resolvedSize !== void 0 && { size: resolvedSize },
+      ...isImagine ? imagineSizeParams(size) : size !== void 0 && {
+        size
+      },
       stream: false,
       ...modelOptions
     };
@@ -70,6 +104,91 @@ class GrokImageAdapter extends BaseImageAdapter {
       throw error;
     }
   }
+  /**
+   * Image-conditioned generation via xAI's Imagine API.
+   *
+   * The `/v1/images/edits` endpoint takes `application/json` (the OpenAI
+   * SDK's `images.edit()` sends `multipart/form-data`, which xAI rejects),
+   * so this path issues the request directly. One input is sent as
+   * `image: { url }`; multiple inputs (up to 3) as `images: [{ url }, ...]`,
+   * addressed by xAI in the order they are sent. The prompt text is sent
+   * verbatim — no referencing markers are injected.
+   */
+  async editImages(options, resolved) {
+    const { model, numberOfImages, size, modelOptions, logger } = options;
+    const prompt = resolved.text;
+    const imageInputs = resolved.images;
+    const unsupportedRole = imageInputs.find(
+      (part) => part.metadata?.role === "mask" || part.metadata?.role === "control"
+    );
+    if (unsupportedRole) {
+      throw new Error(
+        `grok: the Imagine API has no ${unsupportedRole.metadata?.role} input; only source/reference images are supported.`
+      );
+    }
+    if (imageInputs.length > MAX_EDIT_IMAGES) {
+      throw new Error(
+        `grok: model "${model}" accepts at most ${MAX_EDIT_IMAGES} source images; received ${imageInputs.length}.`
+      );
+    }
+    validatePrompt({ prompt });
+    validateImageSize(model, size);
+    validateNumberOfImages(model, numberOfImages);
+    const urls = imageInputs.map((part) => imagePartToUrl(part));
+    const request = {
+      model,
+      prompt,
+      ...urls.length === 1 ? { image: { url: urls[0] } } : { images: urls.map((url) => ({ url })) },
+      ...numberOfImages !== void 0 && { n: numberOfImages },
+      ...imagineSizeParams(size),
+      ...modelOptions
+    };
+    try {
+      logger.request(
+        `activity=image provider=${this.name} model=${model} edit images=${urls.length}`,
+        { provider: this.name, model }
+      );
+      const response = await fetch(
+        `${this.clientConfig.baseURL}/images/edits`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.clientConfig.apiKey}`
+          },
+          body: JSON.stringify(request)
+        }
+      );
+      if (!response.ok) {
+        const body = await response.text();
+        throw new Error(
+          `grok: image edit request failed (${response.status} ${response.statusText}): ${body}`
+        );
+      }
+      const result = await response.json();
+      const images = (result.data ?? []).flatMap(
+        (item) => {
+          if (item.b64_json) return [{ b64Json: item.b64_json }];
+          if (item.url) return [{ url: item.url }];
+          return [];
+        }
+      );
+      if (images.length === 0) {
+        throw new Error("grok: image edit response contained no images");
+      }
+      return {
+        id: generateId(this.name),
+        model,
+        images
+      };
+    } catch (error) {
+      logger.errors(`${this.name}.generateImages fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.generateImages failed`),
+        source: `${this.name}.generateImages`
+      });
+      throw error;
+    }
+  }
 }
 function createGrokImage(model, apiKey, config) {
   return new GrokImageAdapter({ apiKey, ...config }, model);

package/dist/esm/adapters/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sources":["../../../src/adapters/image.ts"],"sourcesContent":["import OpenAI from 'openai'\nimport { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport { toRunErrorPayload } from '@tanstack/ai/adapter-internals'\nimport { buildImagesUsage } from '@tanstack/openai-base'\nimport { generateId } from '@tanstack/ai-utils'\nimport { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'\nimport {\n  validateImageSize,\n  validateNumberOfImages,\n  validatePrompt,\n} from '../image/image-provider-options'\nimport type {\n  GeneratedImage,\n  ImageGenerationOptions,\n  ImageGenerationResult,\n} from '@tanstack/ai'\nimport type OpenAI_SDK from 'openai'\nimport type { GrokImageModel } from '../model-meta'\nimport type {\n  GrokImageModelProviderOptionsByName,\n  GrokImageModelSizeByName,\n  GrokImageProviderOptions,\n} from '../image/image-provider-options'\nimport type { GrokClientConfig } from '../utils'\n\n/**\n * Configuration for Grok image adapter\n */\nexport interface GrokImageConfig extends GrokClientConfig {}\n\n/**\n * Grok Image Generation Adapter\n *\n * Tree-shakeable adapter for Grok image generation functionality.\n * Supports grok-2-image-1212 model.\n *\n * Features:\n * - Model-specific type-safe provider options\n * - Size validation per model\n * - Number of images validation\n */\nexport class GrokImageAdapter<\n  TModel extends GrokImageModel,\n> extends BaseImageAdapter<\n  TModel,\n  GrokImageProviderOptions,\n  GrokImageModelProviderOptionsByName,\n  GrokImageModelSizeByName\n> {\n  override readonly kind = 'image' as const\n  readonly name = 'grok' as const\n\n  protected client: OpenAI\n\n  constructor(config: GrokImageConfig, model: TModel) {\n    super(model, {})\n    this.client = new OpenAI(withGrokDefaults(config))\n  }\n\n  async generateImages(\n    options: ImageGenerationOptions<GrokImageProviderOptions>,\n  ): Promise<ImageGenerationResult> {\n    const { model, prompt, numberOfImages, size, modelOptions } = options\n\n    validatePrompt({ prompt, model })\n    validateImageSize(model, size)\n    validateNumberOfImages(model, numberOfImages)\n\n    const resolvedSize = size as OpenAI_SDK.Images.ImageGenerateParams['size']\n    const request: OpenAI_SDK.Images.ImageGenerateParamsNonStreaming = {\n      model,\n      prompt,\n      n: numberOfImages ?? 1,\n      ...(resolvedSize !== undefined && { size: resolvedSize }),\n      stream: false,\n      ...modelOptions,\n    }\n\n    try {\n      options.logger.request(\n        `activity=image provider=${this.name} model=${model} n=${request.n ?? 1} size=${request.size ?? 'default'}`,\n        { provider: this.name, model },\n      )\n      const response = await this.client.images.generate(request)\n\n      const images: Array<GeneratedImage> = (response.data ?? []).flatMap(\n        (item): Array<GeneratedImage> => {\n          const revisedPrompt = item.revised_prompt\n          if (item.b64_json) {\n            return [\n              {\n                b64Json: item.b64_json,\n                ...(revisedPrompt !== undefined && { revisedPrompt }),\n              },\n            ]\n          }\n          if (item.url) {\n            return [\n              {\n                url: item.url,\n                ...(revisedPrompt !== undefined && { revisedPrompt }),\n              },\n            ]\n          }\n          return []\n        },\n      )\n\n      const usage = buildImagesUsage(response.usage)\n\n      return {\n        id: generateId(this.name),\n        model,\n        images,\n        ...(usage ? { usage } : {}),\n      }\n    } catch (error: unknown) {\n      options.logger.errors(`${this.name}.generateImages fatal`, {\n        error: toRunErrorPayload(error, `${this.name}.generateImages failed`),\n        source: `${this.name}.generateImages`,\n      })\n      throw error\n    }\n  }\n}\n\n/**\n * Creates a Grok image adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'grok-2-image-1212')\n * @param apiKey - Your xAI API key\n * @param config - Optional additional configuration\n * @returns Configured Grok image adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGrokImage('grok-2-image-1212', \"xai-...\");\n *\n * const result = await generateImage({\n *   adapter,\n *   prompt: 'A cute baby sea otter'\n * });\n * ```\n */\nexport function createGrokImage<TModel extends GrokImageModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokImageConfig, 'apiKey'>,\n): GrokImageAdapter<TModel> {\n  return new GrokImageAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Grok image adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * Looks for `XAI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'grok-2-image-1212')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Grok image adapter instance with resolved types\n * @throws Error if XAI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses XAI_API_KEY from environment\n * const adapter = grokImage('grok-2-image-1212');\n *\n * const result = await generateImage({\n *   adapter,\n *   prompt: 'A beautiful sunset over mountains'\n * });\n * ```\n */\nexport function grokImage<TModel extends GrokImageModel>(\n  model: TModel,\n  config?: Omit<GrokImageConfig, 'apiKey'>,\n): GrokImageAdapter<TModel> {\n  const apiKey = getGrokApiKeyFromEnv()\n  return createGrokImage(model, apiKey, config)\n}\n"],"names":[],"mappings":";;;;;;;AAyCO,MAAM,yBAEH,iBAKR;AAAA,EACkB,OAAO;AAAA,EAChB,OAAO;AAAA,EAEN;AAAA,EAEV,YAAY,QAAyB,OAAe;AAClD,UAAM,OAAO,EAAE;AACf,SAAK,SAAS,IAAI,OAAO,iBAAiB,MAAM,CAAC;AAAA,EACnD;AAAA,EAEA,MAAM,eACJ,SACgC;AAChC,UAAM,EAAE,OAAO,QAAQ,gBAAgB,MAAM,iBAAiB;AAE9D,mBAAe,EAAE,OAAc,CAAC;AAChC,sBAAkB,OAAO,IAAI;AAC7B,2BAAuB,OAAO,cAAc;AAE5C,UAAM,eAAe;AACrB,UAAM,UAA6D;AAAA,MACjE;AAAA,MACA;AAAA,MACA,GAAG,kBAAkB;AAAA,MACrB,GAAI,iBAAiB,UAAa,EAAE,MAAM,aAAA;AAAA,MAC1C,QAAQ;AAAA,MACR,GAAG;AAAA,IAAA;AAGL,QAAI;AACF,cAAQ,OAAO;AAAA,QACb,2BAA2B,KAAK,IAAI,UAAU,KAAK,MAAM,QAAQ,KAAK,CAAC,SAAS,QAAQ,QAAQ,SAAS;AAAA,QACzG,EAAE,UAAU,KAAK,MAAM,MAAA;AAAA,MAAM;AAE/B,YAAM,WAAW,MAAM,KAAK,OAAO,OAAO,SAAS,OAAO;AAE1D,YAAM,UAAiC,SAAS,QAAQ,CAAA,GAAI;AAAA,QAC1D,CAAC,SAAgC;AAC/B,gBAAM,gBAAgB,KAAK;AAC3B,cAAI,KAAK,UAAU;AACjB,mBAAO;AAAA,cACL;AAAA,gBACE,SAAS,KAAK;AAAA,gBACd,GAAI,kBAAkB,UAAa,EAAE,cAAA;AAAA,cAAc;AAAA,YACrD;AAAA,UAEJ;AACA,cAAI,KAAK,KAAK;AACZ,mBAAO;AAAA,cACL;AAAA,gBACE,KAAK,KAAK;AAAA,gBACV,GAAI,kBAAkB,UAAa,EAAE,cAAA;AAAA,cAAc;AAAA,YACrD;AAAA,UAEJ;AACA,iBAAO,CAAA;AAAA,QACT;AAAA,MAAA;AAGF,YAAM,QAAQ,iBAAiB,SAAS,KAAK;AAE7C,aAAO;AAAA,QACL,IAAI,WAAW,KAAK,IAAI;AAAA,QACxB;AAAA,QACA;AAAA,QACA,GAAI,QAAQ,EAAE,UAAU,CAAA;AAAA,MAAC;AAAA,IAE7B,SAAS,OAAgB;AACvB,cAAQ,OAAO,OAAO,GAAG,KAAK,IAAI,yBAAyB;AAAA,QACzD,OAAO,kBAAkB,OAAO,GAAG,KAAK,IAAI,wBAAwB;AAAA,QACpE,QAAQ,GAAG,KAAK,IAAI;AAAA,MAAA,CACrB;AACD,YAAM;AAAA,IACR;AAAA,EACF;AACF;AAqBO,SAAS,gBACd,OACA,QACA,QAC0B;AAC1B,SAAO,IAAI,iBAAiB,EAAE,QAAQ,GAAG,OAAA,GAAU,KAAK;AAC1D;AA0BO,SAAS,UACd,OACA,QAC0B;AAC1B,QAAM,SAAS,qBAAA;AACf,SAAO,gBAAgB,OAAO,QAAQ,MAAM;AAC9C;"}
+{"version":3,"file":"image.js","sources":["../../../src/adapters/image.ts"],"sourcesContent":["import OpenAI from 'openai'\nimport { resolveMediaPrompt } from '@tanstack/ai'\nimport { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport { toRunErrorPayload } from '@tanstack/ai/adapter-internals'\nimport { buildImagesUsage } from '@tanstack/openai-base'\nimport { generateId } from '@tanstack/ai-utils'\nimport { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'\nimport {\n  isGrokImagineImageModel,\n  parseGrokImagineSize,\n  validateImageSize,\n  validateNumberOfImages,\n  validatePrompt,\n} from '../image/image-provider-options'\nimport type {\n  GeneratedImage,\n  ImageGenerationOptions,\n  ImageGenerationResult,\n  ImagePart,\n  MediaInputMetadata,\n  ResolvedMediaPrompt,\n} from '@tanstack/ai'\nimport type OpenAI_SDK from 'openai'\nimport type { GrokImageModel } from '../model-meta'\nimport type {\n  GrokImageModelInputModalitiesByName,\n  GrokImageModelProviderOptionsByName,\n  GrokImageModelSizeByName,\n  GrokImageProviderOptions,\n} from '../image/image-provider-options'\nimport type { GrokClientConfig } from '../utils'\n\n/**\n * Configuration for Grok image adapter\n */\nexport interface GrokImageConfig extends GrokClientConfig {}\n\n/** Maximum source images accepted by xAI's image edit endpoint. */\nconst MAX_EDIT_IMAGES = 3\n\n/**\n * Maps the generic `size` option onto Imagine API parameters: the\n * \"aspectRatio_resolution\" template (\"16:9_2k\") splits into `aspect_ratio`\n * and optional `resolution` request fields.\n */\nfunction imagineSizeParams(size: string | undefined): {\n  aspect_ratio?: string\n  resolution?: string\n} {\n  if (!size) return {}\n  const parsed = parseGrokImagineSize(size)\n  if (!parsed) return {}\n  return {\n    aspect_ratio: parsed.aspectRatio,\n    ...(parsed.resolution !== undefined && { resolution: parsed.resolution }),\n  }\n}\n\n/**\n * Convert a TanStack ImagePart to the URL string accepted by xAI's edit\n * endpoint: public URLs pass through (fetched by xAI's servers), data\n * sources become base64 data URIs.\n */\nfunction imagePartToUrl(part: ImagePart<MediaInputMetadata>): string {\n  if (part.source.type === 'url') return part.source.value\n  return `data:${part.source.mimeType};base64,${part.source.value}`\n}\n\n/** Response shape of xAI's `/v1/images/edits` endpoint. */\ninterface GrokImageEditResponse {\n  data?: Array<{\n    url?: string | null\n    b64_json?: string | null\n    mime_type?: string\n  }>\n}\n\n/**\n * Grok Image Generation Adapter\n *\n * Tree-shakeable adapter for Grok image generation functionality.\n * Supports the legacy grok-2-image-1212 model (text-to-image via the\n * OpenAI-compat endpoint) and the grok-imagine image models, which also\n * accept image prompt parts for image-conditioned generation via xAI's\n * `/v1/images/edits` endpoint (up to 3 source images).\n *\n * Features:\n * - Model-specific type-safe provider options\n * - Size / aspect-ratio validation per model\n * - Number of images validation\n */\nexport class GrokImageAdapter<\n  TModel extends GrokImageModel,\n> extends BaseImageAdapter<\n  TModel,\n  GrokImageProviderOptions,\n  GrokImageModelProviderOptionsByName,\n  GrokImageModelSizeByName,\n  GrokImageModelInputModalitiesByName\n> {\n  override readonly kind = 'image' as const\n  readonly name = 'grok' as const\n\n  protected client: OpenAI\n  private readonly clientConfig: GrokImageConfig\n\n  constructor(config: GrokImageConfig, model: TModel) {\n    super(model, {})\n    this.clientConfig = withGrokDefaults(config)\n    this.client = new OpenAI(this.clientConfig)\n  }\n\n  async generateImages(\n    options: ImageGenerationOptions<GrokImageProviderOptions>,\n  ): Promise<ImageGenerationResult> {\n    const { model, numberOfImages, size, modelOptions } = options\n\n    const resolved = resolveMediaPrompt(options.prompt)\n    const prompt = resolved.text\n\n    if (resolved.videos.length > 0 || resolved.audios.length > 0) {\n      throw new Error(\n        `grok.generateImages does not support video / audio prompt parts on model ${model}.`,\n      )\n    }\n\n    if (resolved.images.length > 0) {\n      if (!isGrokImagineImageModel(model)) {\n        throw new Error(\n          `grok: model \"${model}\" does not support image prompt parts. ` +\n            `Image-conditioned generation requires an Imagine API model ` +\n            `('grok-imagine-image' or 'grok-imagine-image-quality').`,\n        )\n      }\n      return await this.editImages(options, resolved)\n    }\n\n    validatePrompt({ prompt, model })\n    validateImageSize(model, size)\n    validateNumberOfImages(model, numberOfImages)\n\n    // grok-imagine models are aspect-ratio sized: the generic `size` option\n    // carries an \"aspectRatio_resolution\" template (e.g. '16:9_2k', like\n    // Gemini native image models) and maps to the Imagine API's\n    // `aspect_ratio` / `resolution` parameters instead of OpenAI-style `size`.\n    const isImagine = isGrokImagineImageModel(model)\n    const request = {\n      model,\n      prompt,\n      n: numberOfImages ?? 1,\n      ...(isImagine\n        ? imagineSizeParams(size)\n        : size !== undefined && {\n            size: size,\n          }),\n      stream: false,\n      ...modelOptions,\n    } as OpenAI_SDK.Images.ImageGenerateParamsNonStreaming\n\n    try {\n      options.logger.request(\n        `activity=image provider=${this.name} model=${model} n=${request.n ?? 1} size=${request.size ?? 'default'}`,\n        { provider: this.name, model },\n      )\n      const response = await this.client.images.generate(request)\n\n      const images: Array<GeneratedImage> = (response.data ?? []).flatMap(\n        (item): Array<GeneratedImage> => {\n          const revisedPrompt = item.revised_prompt\n          if (item.b64_json) {\n            return [\n              {\n                b64Json: item.b64_json,\n                ...(revisedPrompt !== undefined && { revisedPrompt }),\n              },\n            ]\n          }\n          if (item.url) {\n            return [\n              {\n                url: item.url,\n                ...(revisedPrompt !== undefined && { revisedPrompt }),\n              },\n            ]\n          }\n          return []\n        },\n      )\n\n      const usage = buildImagesUsage(response.usage)\n\n      return {\n        id: generateId(this.name),\n        model,\n        images,\n        ...(usage ? { usage } : {}),\n      }\n    } catch (error: unknown) {\n      options.logger.errors(`${this.name}.generateImages fatal`, {\n        error: toRunErrorPayload(error, `${this.name}.generateImages failed`),\n        source: `${this.name}.generateImages`,\n      })\n      throw error\n    }\n  }\n\n  /**\n   * Image-conditioned generation via xAI's Imagine API.\n   *\n   * The `/v1/images/edits` endpoint takes `application/json` (the OpenAI\n   * SDK's `images.edit()` sends `multipart/form-data`, which xAI rejects),\n   * so this path issues the request directly. One input is sent as\n   * `image: { url }`; multiple inputs (up to 3) as `images: [{ url }, ...]`,\n   * addressed by xAI in the order they are sent. The prompt text is sent\n   * verbatim — no referencing markers are injected.\n   */\n  private async editImages(\n    options: ImageGenerationOptions<GrokImageProviderOptions>,\n    resolved: ResolvedMediaPrompt,\n  ): Promise<ImageGenerationResult> {\n    const { model, numberOfImages, size, modelOptions, logger } = options\n    const prompt = resolved.text\n    const imageInputs = resolved.images\n\n    const unsupportedRole = imageInputs.find(\n      (part) =>\n        part.metadata?.role === 'mask' || part.metadata?.role === 'control',\n    )\n    if (unsupportedRole) {\n      throw new Error(\n        `grok: the Imagine API has no ${unsupportedRole.metadata?.role} input; ` +\n          `only source/reference images are supported.`,\n      )\n    }\n    if (imageInputs.length > MAX_EDIT_IMAGES) {\n      throw new Error(\n        `grok: model \"${model}\" accepts at most ${MAX_EDIT_IMAGES} source images; received ${imageInputs.length}.`,\n      )\n    }\n\n    validatePrompt({ prompt, model })\n    validateImageSize(model, size)\n    validateNumberOfImages(model, numberOfImages)\n\n    const urls = imageInputs.map((part) => imagePartToUrl(part))\n    const request: Record<string, unknown> = {\n      model,\n      prompt,\n      ...(urls.length === 1\n        ? { image: { url: urls[0] } }\n        : { images: urls.map((url) => ({ url })) }),\n      ...(numberOfImages !== undefined && { n: numberOfImages }),\n      ...imagineSizeParams(size),\n      ...modelOptions,\n    }\n\n    try {\n      logger.request(\n        `activity=image provider=${this.name} model=${model} edit images=${urls.length}`,\n        { provider: this.name, model },\n      )\n\n      const response = await fetch(\n        `${this.clientConfig.baseURL}/images/edits`,\n        {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${this.clientConfig.apiKey}`,\n          },\n          body: JSON.stringify(request),\n        },\n      )\n      if (!response.ok) {\n        const body = await response.text()\n        throw new Error(\n          `grok: image edit request failed (${response.status} ${response.statusText}): ${body}`,\n        )\n      }\n\n      const result = (await response.json()) as GrokImageEditResponse\n      const images: Array<GeneratedImage> = (result.data ?? []).flatMap(\n        (item): Array<GeneratedImage> => {\n          if (item.b64_json) return [{ b64Json: item.b64_json }]\n          if (item.url) return [{ url: item.url }]\n          return []\n        },\n      )\n      if (images.length === 0) {\n        throw new Error('grok: image edit response contained no images')\n      }\n\n      return {\n        id: generateId(this.name),\n        model,\n        images,\n      }\n    } catch (error: unknown) {\n      logger.errors(`${this.name}.generateImages fatal`, {\n        error: toRunErrorPayload(error, `${this.name}.generateImages failed`),\n        source: `${this.name}.generateImages`,\n      })\n      throw error\n    }\n  }\n}\n\n/**\n * Creates a Grok image adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'grok-2-image-1212')\n * @param apiKey - Your xAI API key\n * @param config - Optional additional configuration\n * @returns Configured Grok image adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGrokImage('grok-2-image-1212', \"xai-...\");\n *\n * const result = await generateImage({\n *   adapter,\n *   prompt: 'A cute baby sea otter'\n * });\n * ```\n */\nexport function createGrokImage<TModel extends GrokImageModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokImageConfig, 'apiKey'>,\n): GrokImageAdapter<TModel> {\n  return new GrokImageAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Grok image adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * Looks for `XAI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'grok-2-image-1212')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Grok image adapter instance with resolved types\n * @throws Error if XAI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses XAI_API_KEY from environment\n * const adapter = grokImage('grok-2-image-1212');\n *\n * const result = await generateImage({\n *   adapter,\n *   prompt: 'A beautiful sunset over mountains'\n * });\n * ```\n */\nexport function grokImage<TModel extends GrokImageModel>(\n  model: TModel,\n  config?: Omit<GrokImageConfig, 'apiKey'>,\n): GrokImageAdapter<TModel> {\n  const apiKey = getGrokApiKeyFromEnv()\n  return createGrokImage(model, apiKey, config)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/image/image-provider-options.d.ts

@@ -8,6 +8,38 @@
  * Supported sizes for grok-2-image-1212 model
  */
 export type GrokImageSize = '1024x1024' | '1536x1024' | '1024x1536';
+/**
+ * Aspect ratios accepted by the grok-imagine image models.
+ */
+export type GrokImagineAspectRatio = '1:1' | '3:4' | '4:3' | '9:16' | '16:9' | '2:3' | '3:2' | '9:19.5' | '19.5:9' | '9:20' | '20:9' | '1:2' | '2:1' | 'auto';
+/**
+ * Resolution tiers for the grok-imagine image models.
+ */
+export type GrokImagineResolution = '1k' | '2k';
+/**
+ * Size strings for grok-imagine image models. The Imagine API is
+ * aspect-ratio based rather than pixel-size based; like Gemini's native
+ * image models, the generic `size` option uses an
+ * `aspectRatio_resolution` template ("16:9_2k") — the resolution suffix is
+ * optional ("16:9" uses the API default of 1k).
+ */
+export type GrokImagineImageSize = GrokImagineAspectRatio | `${GrokImagineAspectRatio}_${GrokImagineResolution}`;
+/**
+ * Models served by xAI's Imagine API. They are aspect-ratio sized and
+ * support image-conditioned generation via `/v1/images/edits`; the legacy
+ * grok-2-image-1212 model is pixel-sized and text-to-image only.
+ */
+export declare function isGrokImagineImageModel(model: string): boolean;
+/**
+ * Parses a grok-imagine size string into its components.
+ * Format: "aspectRatio" or "aspectRatio_resolution",
+ * e.g. "16:9_2k" → { aspectRatio: "16:9", resolution: "2k" }.
+ * Returns undefined when the string doesn't match the template.
+ */
+export declare function parseGrokImagineSize(size: string): {
+    aspectRatio: string;
+    resolution?: string;
+} | undefined;
 /**
  * Base provider options for Grok image models
  */
@@ -34,17 +66,52 @@ export interface GrokImageProviderOptions extends GrokImageBaseProviderOptions {
      */
     response_format?: 'url' | 'b64_json';
 }
+/**
+ * Provider options for the grok-imagine image models (generation and
+ * image-conditioned editing via xAI's Imagine API).
+ */
+export interface GrokImagineImageProviderOptions extends GrokImageBaseProviderOptions {
+    /**
+     * The format in which generated images are returned.
+     * @default 'url'
+     */
+    response_format?: 'url' | 'b64_json';
+    /**
+     * Output resolution.
+     * @default '1k'
+     */
+    resolution?: '1k' | '2k';
+    /**
+     * Processing tier for the request.
+     * @default 'default'
+     */
+    service_tier?: 'default' | 'priority';
+}
 /**
  * Type-only map from model name to its specific provider options.
  */
 export type GrokImageModelProviderOptionsByName = {
     'grok-2-image-1212': GrokImageProviderOptions;
+    'grok-imagine-image': GrokImagineImageProviderOptions;
+    'grok-imagine-image-quality': GrokImagineImageProviderOptions;
 };
 /**
  * Type-only map from model name to its supported sizes.
  */
 export type GrokImageModelSizeByName = {
     'grok-2-image-1212': GrokImageSize;
+    'grok-imagine-image': GrokImagineImageSize;
+    'grok-imagine-image-quality': GrokImagineImageSize;
+};
+/**
+ * Per-model prompt input modalities. Imagine API models accept image parts
+ * in the prompt (routed to `/v1/images/edits`, up to 3 images, addressed by
+ * xAI in request order); grok-2-image is text-to-image only.
+ */
+export type GrokImageModelInputModalitiesByName = {
+    'grok-2-image-1212': readonly [];
+    'grok-imagine-image': readonly ['image'];
+    'grok-imagine-image-quality': readonly ['image'];
 };
 /**
  * Internal options interface for validation

package/dist/esm/image/image-provider-options.js

@@ -1,5 +1,40 @@
+const GROK_IMAGINE_ASPECT_RATIOS = [
+  "1:1",
+  "3:4",
+  "4:3",
+  "9:16",
+  "16:9",
+  "2:3",
+  "3:2",
+  "9:19.5",
+  "19.5:9",
+  "9:20",
+  "20:9",
+  "1:2",
+  "2:1",
+  "auto"
+];
+const GROK_IMAGINE_RESOLUTIONS = ["1k", "2k"];
+function isGrokImagineImageModel(model) {
+  return model.startsWith("grok-imagine-image");
+}
+function parseGrokImagineSize(size) {
+  const match = size.match(/^([\d.]+:[\d.]+|auto)(?:_(.+))?$/);
+  const [, aspectRatio, resolution] = match ?? [];
+  if (aspectRatio === void 0) return void 0;
+  return { aspectRatio, ...resolution !== void 0 && { resolution } };
+}
 function validateImageSize(model, size) {
   if (!size) return;
+  if (isGrokImagineImageModel(model)) {
+    const parsed = parseGrokImagineSize(size);
+    if (!parsed || !GROK_IMAGINE_ASPECT_RATIOS.includes(parsed.aspectRatio) || parsed.resolution !== void 0 && !GROK_IMAGINE_RESOLUTIONS.includes(parsed.resolution)) {
+      throw new Error(
+        `Size "${size}" is not supported by model "${model}". Expected an aspect ratio (${GROK_IMAGINE_ASPECT_RATIOS.join(", ")}) optionally suffixed with a resolution ("16:9_2k"; resolutions: ${GROK_IMAGINE_RESOLUTIONS.join(", ")}).`
+      );
+    }
+    return;
+  }
   const validSizes = {
     "grok-2-image-1212": ["1024x1024", "1536x1024", "1024x1536"]
   };
@@ -32,6 +67,8 @@ const validatePrompt = (options) => {
   }
 };
 export {
+  isGrokImagineImageModel,
+  parseGrokImagineSize,
   validateImageSize,
   validateNumberOfImages,
   validatePrompt

package/dist/esm/image/image-provider-options.js.map

@@ -1 +1 @@
-{"version":3,"file":"image-provider-options.js","sources":["../../../src/image/image-provider-options.ts"],"sourcesContent":["/**\n * Grok Image Generation Provider Options\n *\n * These are provider-specific options for Grok image generation.\n * Grok uses the grok-2-image-1212 model for image generation.\n */\n\n/**\n * Supported sizes for grok-2-image-1212 model\n */\nexport type GrokImageSize = '1024x1024' | '1536x1024' | '1024x1536'\n\n/**\n * Base provider options for Grok image models\n */\nexport interface GrokImageBaseProviderOptions {\n  /**\n   * A unique identifier representing your end-user.\n   * Can help xAI to monitor and detect abuse.\n   */\n  user?: string\n}\n\n/**\n * Provider options for grok-2-image-1212 model\n */\nexport interface GrokImageProviderOptions extends GrokImageBaseProviderOptions {\n  /**\n   * The quality of the image.\n   * @default 'standard'\n   */\n  quality?: 'standard' | 'hd'\n\n  /**\n   * The format in which generated images are returned.\n   * URLs are only valid for 60 minutes after generation.\n   * @default 'url'\n   */\n  response_format?: 'url' | 'b64_json'\n}\n\n/**\n * Type-only map from model name to its specific provider options.\n */\nexport type GrokImageModelProviderOptionsByName = {\n  'grok-2-image-1212': GrokImageProviderOptions\n}\n\n/**\n * Type-only map from model name to its supported sizes.\n */\nexport type GrokImageModelSizeByName = {\n  'grok-2-image-1212': GrokImageSize\n}\n\n/**\n * Internal options interface for validation\n */\ninterface ImageValidationOptions {\n  prompt: string\n  model: string\n}\n\n/**\n * Validates that the provided size is supported by the model.\n * Throws a descriptive error if the size is not supported.\n */\nexport function validateImageSize(\n  model: string,\n  size: string | undefined,\n): void {\n  if (!size) return\n\n  const validSizes: Record<string, Array<string>> = {\n    'grok-2-image-1212': ['1024x1024', '1536x1024', '1024x1536'],\n  }\n\n  const modelSizes = validSizes[model]\n  if (!modelSizes) {\n    throw new Error(`Unknown image model: ${model}`)\n  }\n\n  if (!modelSizes.includes(size)) {\n    throw new Error(\n      `Size \"${size}\" is not supported by model \"${model}\". ` +\n        `Supported sizes: ${modelSizes.join(', ')}`,\n    )\n  }\n}\n\n/**\n * Validates that the number of images is within bounds for the model.\n */\nexport function validateNumberOfImages(\n  _model: string,\n  numberOfImages: number | undefined,\n): void {\n  if (numberOfImages === undefined) return\n\n  // grok-2-image-1212 supports 1-10 images per request\n  if (numberOfImages < 1 || numberOfImages > 10) {\n    throw new Error(\n      `Number of images must be between 1 and 10. Requested: ${numberOfImages}`,\n    )\n  }\n}\n\nexport const validatePrompt = (options: ImageValidationOptions) => {\n  if (options.prompt.length === 0) {\n    throw new Error('Prompt cannot be empty.')\n  }\n  // Grok image model supports up to 4000 characters\n  if (options.prompt.length > 4000) {\n    throw new Error(\n      'For grok-2-image-1212, prompt length must be less than or equal to 4000 characters.',\n    )\n  }\n}\n"],"names":[],"mappings":"AAmEO,SAAS,kBACd,OACA,MACM;AACN,MAAI,CAAC,KAAM;AAEX,QAAM,aAA4C;AAAA,IAChD,qBAAqB,CAAC,aAAa,aAAa,WAAW;AAAA,EAAA;AAG7D,QAAM,aAAa,WAAW,KAAK;AACnC,MAAI,CAAC,YAAY;AACf,UAAM,IAAI,MAAM,wBAAwB,KAAK,EAAE;AAAA,EACjD;AAEA,MAAI,CAAC,WAAW,SAAS,IAAI,GAAG;AAC9B,UAAM,IAAI;AAAA,MACR,SAAS,IAAI,gCAAgC,KAAK,uBAC5B,WAAW,KAAK,IAAI,CAAC;AAAA,IAAA;AAAA,EAE/C;AACF;AAKO,SAAS,uBACd,QACA,gBACM;AACN,MAAI,mBAAmB,OAAW;AAGlC,MAAI,iBAAiB,KAAK,iBAAiB,IAAI;AAC7C,UAAM,IAAI;AAAA,MACR,yDAAyD,cAAc;AAAA,IAAA;AAAA,EAE3E;AACF;AAEO,MAAM,iBAAiB,CAAC,YAAoC;AACjE,MAAI,QAAQ,OAAO,WAAW,GAAG;AAC/B,UAAM,IAAI,MAAM,yBAAyB;AAAA,EAC3C;AAEA,MAAI,QAAQ,OAAO,SAAS,KAAM;AAChC,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AACF;"}
+{"version":3,"file":"image-provider-options.js","sources":["../../../src/image/image-provider-options.ts"],"sourcesContent":["/**\n * Grok Image Generation Provider Options\n *\n * These are provider-specific options for Grok image generation.\n * Grok uses the grok-2-image-1212 model for image generation.\n */\n\n/**\n * Supported sizes for grok-2-image-1212 model\n */\nexport type GrokImageSize = '1024x1024' | '1536x1024' | '1024x1536'\n\n/**\n * Aspect ratios accepted by the grok-imagine image models.\n */\nexport type GrokImagineAspectRatio =\n  | '1:1'\n  | '3:4'\n  | '4:3'\n  | '9:16'\n  | '16:9'\n  | '2:3'\n  | '3:2'\n  | '9:19.5'\n  | '19.5:9'\n  | '9:20'\n  | '20:9'\n  | '1:2'\n  | '2:1'\n  | 'auto'\n\n/**\n * Resolution tiers for the grok-imagine image models.\n */\nexport type GrokImagineResolution = '1k' | '2k'\n\n/**\n * Size strings for grok-imagine image models. The Imagine API is\n * aspect-ratio based rather than pixel-size based; like Gemini's native\n * image models, the generic `size` option uses an\n * `aspectRatio_resolution` template (\"16:9_2k\") — the resolution suffix is\n * optional (\"16:9\" uses the API default of 1k).\n */\nexport type GrokImagineImageSize =\n  | GrokImagineAspectRatio\n  | `${GrokImagineAspectRatio}_${GrokImagineResolution}`\n\nconst GROK_IMAGINE_ASPECT_RATIOS: ReadonlyArray<string> = [\n  '1:1',\n  '3:4',\n  '4:3',\n  '9:16',\n  '16:9',\n  '2:3',\n  '3:2',\n  '9:19.5',\n  '19.5:9',\n  '9:20',\n  '20:9',\n  '1:2',\n  '2:1',\n  'auto',\n]\n\nconst GROK_IMAGINE_RESOLUTIONS: ReadonlyArray<string> = ['1k', '2k']\n\n/**\n * Models served by xAI's Imagine API. They are aspect-ratio sized and\n * support image-conditioned generation via `/v1/images/edits`; the legacy\n * grok-2-image-1212 model is pixel-sized and text-to-image only.\n */\nexport function isGrokImagineImageModel(model: string): boolean {\n  return model.startsWith('grok-imagine-image')\n}\n\n/**\n * Parses a grok-imagine size string into its components.\n * Format: \"aspectRatio\" or \"aspectRatio_resolution\",\n * e.g. \"16:9_2k\" → { aspectRatio: \"16:9\", resolution: \"2k\" }.\n * Returns undefined when the string doesn't match the template.\n */\nexport function parseGrokImagineSize(\n  size: string,\n): { aspectRatio: string; resolution?: string } | undefined {\n  const match = size.match(/^([\\d.]+:[\\d.]+|auto)(?:_(.+))?$/)\n  const [, aspectRatio, resolution] = match ?? []\n  if (aspectRatio === undefined) return undefined\n  return { aspectRatio, ...(resolution !== undefined && { resolution }) }\n}\n\n/**\n * Base provider options for Grok image models\n */\nexport interface GrokImageBaseProviderOptions {\n  /**\n   * A unique identifier representing your end-user.\n   * Can help xAI to monitor and detect abuse.\n   */\n  user?: string\n}\n\n/**\n * Provider options for grok-2-image-1212 model\n */\nexport interface GrokImageProviderOptions extends GrokImageBaseProviderOptions {\n  /**\n   * The quality of the image.\n   * @default 'standard'\n   */\n  quality?: 'standard' | 'hd'\n\n  /**\n   * The format in which generated images are returned.\n   * URLs are only valid for 60 minutes after generation.\n   * @default 'url'\n   */\n  response_format?: 'url' | 'b64_json'\n}\n\n/**\n * Provider options for the grok-imagine image models (generation and\n * image-conditioned editing via xAI's Imagine API).\n */\nexport interface GrokImagineImageProviderOptions extends GrokImageBaseProviderOptions {\n  /**\n   * The format in which generated images are returned.\n   * @default 'url'\n   */\n  response_format?: 'url' | 'b64_json'\n\n  /**\n   * Output resolution.\n   * @default '1k'\n   */\n  resolution?: '1k' | '2k'\n\n  /**\n   * Processing tier for the request.\n   * @default 'default'\n   */\n  service_tier?: 'default' | 'priority'\n}\n\n/**\n * Type-only map from model name to its specific provider options.\n */\nexport type GrokImageModelProviderOptionsByName = {\n  'grok-2-image-1212': GrokImageProviderOptions\n  'grok-imagine-image': GrokImagineImageProviderOptions\n  'grok-imagine-image-quality': GrokImagineImageProviderOptions\n}\n\n/**\n * Type-only map from model name to its supported sizes.\n */\nexport type GrokImageModelSizeByName = {\n  'grok-2-image-1212': GrokImageSize\n  'grok-imagine-image': GrokImagineImageSize\n  'grok-imagine-image-quality': GrokImagineImageSize\n}\n\n/**\n * Per-model prompt input modalities. Imagine API models accept image parts\n * in the prompt (routed to `/v1/images/edits`, up to 3 images, addressed by\n * xAI in request order); grok-2-image is text-to-image only.\n */\nexport type GrokImageModelInputModalitiesByName = {\n  'grok-2-image-1212': readonly []\n  'grok-imagine-image': readonly ['image']\n  'grok-imagine-image-quality': readonly ['image']\n}\n\n/**\n * Internal options interface for validation\n */\ninterface ImageValidationOptions {\n  prompt: string\n  model: string\n}\n\n/**\n * Validates that the provided size is supported by the model.\n * Throws a descriptive error if the size is not supported.\n */\nexport function validateImageSize(\n  model: string,\n  size: string | undefined,\n): void {\n  if (!size) return\n\n  if (isGrokImagineImageModel(model)) {\n    const parsed = parseGrokImagineSize(size)\n    if (\n      !parsed ||\n      !GROK_IMAGINE_ASPECT_RATIOS.includes(parsed.aspectRatio) ||\n      (parsed.resolution !== undefined &&\n        !GROK_IMAGINE_RESOLUTIONS.includes(parsed.resolution))\n    ) {\n      throw new Error(\n        `Size \"${size}\" is not supported by model \"${model}\". ` +\n          `Expected an aspect ratio (${GROK_IMAGINE_ASPECT_RATIOS.join(', ')}) ` +\n          `optionally suffixed with a resolution (\"16:9_2k\"; resolutions: ${GROK_IMAGINE_RESOLUTIONS.join(', ')}).`,\n      )\n    }\n    return\n  }\n\n  const validSizes: Record<string, Array<string>> = {\n    'grok-2-image-1212': ['1024x1024', '1536x1024', '1024x1536'],\n  }\n\n  const modelSizes = validSizes[model]\n  if (!modelSizes) {\n    throw new Error(`Unknown image model: ${model}`)\n  }\n\n  if (!modelSizes.includes(size)) {\n    throw new Error(\n      `Size \"${size}\" is not supported by model \"${model}\". ` +\n        `Supported sizes: ${modelSizes.join(', ')}`,\n    )\n  }\n}\n\n/**\n * Validates that the number of images is within bounds for the model.\n */\nexport function validateNumberOfImages(\n  _model: string,\n  numberOfImages: number | undefined,\n): void {\n  if (numberOfImages === undefined) return\n\n  // grok-2-image-1212 supports 1-10 images per request\n  if (numberOfImages < 1 || numberOfImages > 10) {\n    throw new Error(\n      `Number of images must be between 1 and 10. Requested: ${numberOfImages}`,\n    )\n  }\n}\n\nexport const validatePrompt = (options: ImageValidationOptions) => {\n  if (options.prompt.length === 0) {\n    throw new Error('Prompt cannot be empty.')\n  }\n  // Grok image model supports up to 4000 characters\n  if (options.prompt.length > 4000) {\n    throw new Error(\n      'For grok-2-image-1212, prompt length must be less than or equal to 4000 characters.',\n    )\n  }\n}\n"],"names":[],"mappings":"AA+CA,MAAM,6BAAoD;AAAA,EACxD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,MAAM,2BAAkD,CAAC,MAAM,IAAI;AAO5D,SAAS,wBAAwB,OAAwB;AAC9D,SAAO,MAAM,WAAW,oBAAoB;AAC9C;AAQO,SAAS,qBACd,MAC0D;AAC1D,QAAM,QAAQ,KAAK,MAAM,kCAAkC;AAC3D,QAAM,GAAG,aAAa,UAAU,IAAI,SAAS,CAAA;AAC7C,MAAI,gBAAgB,OAAW,QAAO;AACtC,SAAO,EAAE,aAAa,GAAI,eAAe,UAAa,EAAE,aAAW;AACrE;AAgGO,SAAS,kBACd,OACA,MACM;AACN,MAAI,CAAC,KAAM;AAEX,MAAI,wBAAwB,KAAK,GAAG;AAClC,UAAM,SAAS,qBAAqB,IAAI;AACxC,QACE,CAAC,UACD,CAAC,2BAA2B,SAAS,OAAO,WAAW,KACtD,OAAO,eAAe,UACrB,CAAC,yBAAyB,SAAS,OAAO,UAAU,GACtD;AACA,YAAM,IAAI;AAAA,QACR,SAAS,IAAI,gCAAgC,KAAK,gCACnB,2BAA2B,KAAK,IAAI,CAAC,oEACA,yBAAyB,KAAK,IAAI,CAAC;AAAA,MAAA;AAAA,IAE3G;AACA;AAAA,EACF;AAEA,QAAM,aAA4C;AAAA,IAChD,qBAAqB,CAAC,aAAa,aAAa,WAAW;AAAA,EAAA;AAG7D,QAAM,aAAa,WAAW,KAAK;AACnC,MAAI,CAAC,YAAY;AACf,UAAM,IAAI,MAAM,wBAAwB,KAAK,EAAE;AAAA,EACjD;AAEA,MAAI,CAAC,WAAW,SAAS,IAAI,GAAG;AAC9B,UAAM,IAAI;AAAA,MACR,SAAS,IAAI,gCAAgC,KAAK,uBAC5B,WAAW,KAAK,IAAI,CAAC;AAAA,IAAA;AAAA,EAE/C;AACF;AAKO,SAAS,uBACd,QACA,gBACM;AACN,MAAI,mBAAmB,OAAW;AAGlC,MAAI,iBAAiB,KAAK,iBAAiB,IAAI;AAC7C,UAAM,IAAI;AAAA,MACR,yDAAyD,cAAc;AAAA,IAAA;AAAA,EAE3E;AACF;AAEO,MAAM,iBAAiB,CAAC,YAAoC;AACjE,MAAI,QAAQ,OAAO,WAAW,GAAG;AAC/B,UAAM,IAAI,MAAM,yBAAyB;AAAA,EAC3C;AAEA,MAAI,QAAQ,OAAO,SAAS,KAAM;AAChC,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AACF;"}

package/dist/esm/model-meta.d.ts

@@ -265,7 +265,7 @@ export declare const GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS: Set<string>;
 /**
  * Grok Image Generation Models
  */
-export declare const GROK_IMAGE_MODELS: readonly ["grok-2-image-1212"];
+export declare const GROK_IMAGE_MODELS: readonly ["grok-2-image-1212", "grok-imagine-image", "grok-imagine-image-quality"];
 export declare const GROK_TTS_MODELS: readonly ["grok-tts"];
 export declare const GROK_TRANSCRIPTION_MODELS: readonly ["grok-stt"];
 export declare const GROK_REALTIME_MODELS: readonly ["grok-voice-fast-1.0", "grok-voice-think-fast-1.0"];

package/dist/esm/model-meta.js

@@ -28,6 +28,12 @@ const GROK_2_VISION = {
 const GROK_2_IMAGE = {
   name: "grok-2-image-1212"
 };
+const GROK_IMAGINE_IMAGE = {
+  name: "grok-imagine-image"
+};
+const GROK_IMAGINE_IMAGE_QUALITY = {
+  name: "grok-imagine-image-quality"
+};
 const GROK_4_20 = {
   name: "grok-4.20"
 };
@@ -66,7 +72,11 @@ const GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS = /* @__PURE__ */ new Set([
   GROK_4_20_MULTI_AGENT.name,
   GROK_4_3.name
 ]);
-const GROK_IMAGE_MODELS = [GROK_2_IMAGE.name];
+const GROK_IMAGE_MODELS = [
+  GROK_2_IMAGE.name,
+  GROK_IMAGINE_IMAGE.name,
+  GROK_IMAGINE_IMAGE_QUALITY.name
+];
 const GROK_TTS = {
   name: "grok-tts"
 };

package/dist/esm/model-meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"model-meta.js","sources":["../../src/model-meta.ts"],"sourcesContent":["/**\n * Model metadata interface for documentation and type inference\n */\ninterface ModelMeta {\n  name: string\n  supports: {\n    input: Array<'text' | 'image' | 'audio' | 'video' | 'document'>\n    output: Array<'text' | 'image' | 'audio' | 'video'>\n    capabilities?: Array<'reasoning' | 'tool_calling' | 'structured_outputs'>\n    tools?: ReadonlyArray<never>\n  }\n  max_input_tokens?: number\n  max_output_tokens?: number\n  context_window?: number\n  knowledge_cutoff?: string\n  pricing?: {\n    input: {\n      normal: number\n      cached?: number\n    }\n    output: {\n      normal: number\n    }\n  }\n}\n\nconst GROK_4_1_FAST_REASONING = {\n  name: 'grok-4-1-fast-reasoning',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.05,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_1_FAST_NON_REASONING = {\n  name: 'grok-4-1-fast-non-reasoning',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.05,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_CODE_FAST_1 = {\n  name: 'grok-code-fast-1',\n  context_window: 256_000,\n  supports: {\n    input: ['text'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.02,\n    },\n    output: {\n      normal: 1.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_FAST_REASONING = {\n  name: 'grok-4-fast-reasoning',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.05,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_FAST_NON_REASONING = {\n  name: 'grok-4-fast-non-reasoning',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.05,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4 = {\n  name: 'grok-4',\n  context_window: 256_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 3,\n      cached: 0.75,\n    },\n    output: {\n      normal: 15,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_3_MINI = {\n  name: 'grok-3-mini',\n  context_window: 131_072,\n  supports: {\n    input: ['text'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.3,\n      cached: 0.075,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_3 = {\n  name: 'grok-3',\n  context_window: 131_072,\n  supports: {\n    input: ['text'],\n    output: ['text'],\n    capabilities: ['structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 3,\n      cached: 0.75,\n    },\n    output: {\n      normal: 15,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_2_VISION = {\n  name: 'grok-2-vision-1212',\n  context_window: 32_768,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 2,\n    },\n    output: {\n      normal: 10,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_2_IMAGE = {\n  name: 'grok-2-image-1212',\n  supports: {\n    input: ['text'],\n    output: ['image'],\n  },\n  pricing: {\n    input: {\n      normal: 0.07,\n    },\n    output: {\n      normal: 0.07,\n    },\n  },\n} as const satisfies ModelMeta\n\n/**\n * Grok Chat Models\n * Based on xAI's available models as of 2025\n */\nconst GROK_4_20 = {\n  name: 'grok-4.20',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image', 'document'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 2,\n      cached: 0.2,\n    },\n    output: {\n      normal: 6,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_20_MULTI_AGENT = {\n  name: 'grok-4.20-multi-agent',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image', 'document'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 2,\n      cached: 0.2,\n    },\n    output: {\n      normal: 6,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_3 = {\n  name: 'grok-4.3',\n  context_window: 1_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [],\n  },\n  pricing: {\n    input: {\n      normal: 1.25,\n      cached: 0.2,\n    },\n    output: {\n      normal: 2.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_BUILD_0_1 = {\n  name: 'grok-build-0.1',\n  context_window: 256_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [],\n  },\n  pricing: {\n    input: {\n      normal: 1,\n      cached: 0.2,\n    },\n    output: {\n      normal: 2,\n    },\n  },\n} as const satisfies ModelMeta\n\nexport const GROK_CHAT_MODELS = [\n  GROK_4_1_FAST_REASONING.name,\n  GROK_4_1_FAST_NON_REASONING.name,\n  GROK_CODE_FAST_1.name,\n  GROK_4_FAST_REASONING.name,\n  GROK_4_FAST_NON_REASONING.name,\n  GROK_4.name,\n  GROK_3.name,\n  GROK_3_MINI.name,\n  GROK_2_VISION.name,\n\n  GROK_4_20.name,\n  GROK_4_20_MULTI_AGENT.name,\n\n  GROK_4_3.name,\n\n  GROK_BUILD_0_1.name,\n] as const\n\n/**\n * Grok models that support combining `tools` + `response_format: json_schema`\n * in a single streaming Chat Completions request (per issue #605). xAI\n * docs gate this to the Grok 4 family — Grok 2 / 3 reject the\n * combination. Grok 2 image generation is not a chat model, omitted.\n *\n * Note: Grok streams tool-call arguments atomically (not token-streamed)\n * per the issue's source matrix; partial-JSON tool-arg parsing should be\n * skipped for Grok specifically. That's a separate adapter concern from\n * this set — the set only gates whether the engine takes the native\n * combined path vs the legacy finalization path.\n */\nexport const GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS = new Set<string>([\n  GROK_4_1_FAST_REASONING.name,\n  GROK_4_1_FAST_NON_REASONING.name,\n  GROK_CODE_FAST_1.name,\n  GROK_4_FAST_REASONING.name,\n  GROK_4_FAST_NON_REASONING.name,\n  GROK_4.name,\n  GROK_4_20.name,\n  GROK_4_20_MULTI_AGENT.name,\n  GROK_4_3.name,\n])\n\n/**\n * Grok Image Generation Models\n */\nexport const GROK_IMAGE_MODELS = [GROK_2_IMAGE.name] as const\n\n// xAI's `/v1/tts` endpoint is endpoint-addressed and does not take a `model`\n// parameter. This synthetic identifier satisfies the SDK's `TTSOptions.model`\n// contract and provides a stable value for logging and fixture matching.\nconst GROK_TTS = {\n  name: 'grok-tts',\n  supports: {\n    input: ['text'],\n    output: ['audio'],\n  },\n} as const satisfies ModelMeta\n\n// xAI's `/v1/stt` endpoint is endpoint-addressed and does not take a `model`\n// parameter. This synthetic identifier satisfies the SDK's\n// `TranscriptionOptions.model` contract.\nconst GROK_STT = {\n  name: 'grok-stt',\n  supports: {\n    input: ['audio'],\n    output: ['text'],\n  },\n} as const satisfies ModelMeta\n\nconst GROK_VOICE_FAST_1 = {\n  name: 'grok-voice-fast-1.0',\n  supports: {\n    input: ['audio', 'text'],\n    output: ['audio', 'text'],\n    capabilities: ['tool_calling'],\n    tools: [] as const,\n  },\n} as const satisfies ModelMeta\n\nconst GROK_VOICE_THINK_FAST_1 = {\n  name: 'grok-voice-think-fast-1.0',\n  supports: {\n    input: ['audio', 'text'],\n    output: ['audio', 'text'],\n    capabilities: ['reasoning', 'tool_calling'],\n    tools: [] as const,\n  },\n} as const satisfies ModelMeta\n\nexport const GROK_TTS_MODELS = [GROK_TTS.name] as const\n\nexport const GROK_TRANSCRIPTION_MODELS = [GROK_STT.name] as const\n\nexport const GROK_REALTIME_MODELS = [\n  GROK_VOICE_FAST_1.name,\n  GROK_VOICE_THINK_FAST_1.name,\n] as const\n\nexport type GrokChatModel = (typeof GROK_CHAT_MODELS)[number]\nexport type GrokImageModel = (typeof GROK_IMAGE_MODELS)[number]\nexport type GrokTTSModel = (typeof GROK_TTS_MODELS)[number]\nexport type GrokTranscriptionModel = (typeof GROK_TRANSCRIPTION_MODELS)[number]\nexport type GrokRealtimeModel = (typeof GROK_REALTIME_MODELS)[number]\n\n/**\n * Type-only map from Grok chat model name to its supported input modalities.\n * Used for type inference when constructing multimodal messages.\n */\nexport type GrokModelInputModalitiesByName = {\n  [GROK_4_1_FAST_REASONING.name]: typeof GROK_4_1_FAST_REASONING.supports.input\n  [GROK_4_1_FAST_NON_REASONING.name]: typeof GROK_4_1_FAST_NON_REASONING.supports.input\n  [GROK_CODE_FAST_1.name]: typeof GROK_CODE_FAST_1.supports.input\n  [GROK_4_FAST_REASONING.name]: typeof GROK_4_FAST_REASONING.supports.input\n  [GROK_4_FAST_NON_REASONING.name]: typeof GROK_4_FAST_NON_REASONING.supports.input\n  [GROK_4.name]: typeof GROK_4.supports.input\n  [GROK_3.name]: typeof GROK_3.supports.input\n  [GROK_3_MINI.name]: typeof GROK_3_MINI.supports.input\n  [GROK_2_VISION.name]: typeof GROK_2_VISION.supports.input\n  [GROK_4_20.name]: typeof GROK_4_20.supports.input\n  [GROK_4_20_MULTI_AGENT.name]: typeof GROK_4_20_MULTI_AGENT.supports.input\n  [GROK_4_3.name]: typeof GROK_4_3.supports.input\n  [GROK_BUILD_0_1.name]: typeof GROK_BUILD_0_1.supports.input\n}\n\n/**\n * Type-only map from Grok chat model name to its provider options type.\n * Since Grok uses OpenAI-compatible API, we reuse OpenAI provider options.\n */\nexport type GrokChatModelProviderOptionsByName = {\n  [K in (typeof GROK_CHAT_MODELS)[number]]: GrokProviderOptions\n}\n\n/**\n * Type-only map from Grok chat model name to its supported provider tools.\n * Grok exposes no provider-specific tool factories, so every model gets an\n * empty tuple. This ensures that passing an Anthropic/OpenAI ProviderTool to\n * a Grok adapter produces a compile-time type error.\n */\nexport type GrokChatModelToolCapabilitiesByName = {\n  [GROK_4_1_FAST_REASONING.name]: typeof GROK_4_1_FAST_REASONING.supports.tools\n  [GROK_4_1_FAST_NON_REASONING.name]: typeof GROK_4_1_FAST_NON_REASONING.supports.tools\n  [GROK_CODE_FAST_1.name]: typeof GROK_CODE_FAST_1.supports.tools\n  [GROK_4_FAST_REASONING.name]: typeof GROK_4_FAST_REASONING.supports.tools\n  [GROK_4_FAST_NON_REASONING.name]: typeof GROK_4_FAST_NON_REASONING.supports.tools\n  [GROK_4.name]: typeof GROK_4.supports.tools\n  [GROK_3.name]: typeof GROK_3.supports.tools\n  [GROK_3_MINI.name]: typeof GROK_3_MINI.supports.tools\n  [GROK_2_VISION.name]: typeof GROK_2_VISION.supports.tools\n  [GROK_4_20.name]: typeof GROK_4_20.supports.tools\n  [GROK_4_20_MULTI_AGENT.name]: typeof GROK_4_20_MULTI_AGENT.supports.tools\n}\n\n/**\n * Grok-specific provider options\n * Based on OpenAI-compatible API options\n */\nexport interface GrokProviderOptions {\n  /** Temperature for response generation (0-2) */\n  temperature?: number\n  /** Maximum tokens in the response */\n  max_tokens?: number\n  /** Top-p sampling parameter */\n  top_p?: number\n  /** Frequency penalty (-2.0 to 2.0) */\n  frequency_penalty?: number\n  /** Presence penalty (-2.0 to 2.0) */\n  presence_penalty?: number\n  /** Stop sequences */\n  stop?: string | Array<string>\n  /** A unique identifier representing your end-user */\n  user?: string\n}\n\n// ===========================\n// Type Resolution Helpers\n// ===========================\n\n/**\n * Resolve provider options for a specific model.\n * If the model has explicit options in the map, use those; otherwise use base options.\n */\nexport type ResolveProviderOptions<TModel extends string> =\n  TModel extends keyof GrokChatModelProviderOptionsByName\n    ? GrokChatModelProviderOptionsByName[TModel]\n    : GrokProviderOptions\n\n/**\n * Resolve input modalities for a specific model.\n * If the model has explicit modalities in the map, use those; otherwise use text only.\n */\nexport type ResolveInputModalities<TModel extends string> =\n  TModel extends keyof GrokModelInputModalitiesByName\n    ? GrokModelInputModalitiesByName[TModel]\n    : readonly ['text']\n"],"names":[],"mappings":"AA0BA,MAAM,0BAA0B;AAAA,EAC9B,MAAM;AAiBR;AAEA,MAAM,8BAA8B;AAAA,EAClC,MAAM;AAiBR;AAEA,MAAM,mBAAmB;AAAA,EACvB,MAAM;AAiBR;AAEA,MAAM,wBAAwB;AAAA,EAC5B,MAAM;AAiBR;AAEA,MAAM,4BAA4B;AAAA,EAChC,MAAM;AAiBR;AAEA,MAAM,SAAS;AAAA,EACb,MAAM;AAiBR;AAEA,MAAM,cAAc;AAAA,EAClB,MAAM;AAiBR;AAEA,MAAM,SAAS;AAAA,EACb,MAAM;AAiBR;AAEA,MAAM,gBAAgB;AAAA,EACpB,MAAM;AAgBR;AAEA,MAAM,eAAe;AAAA,EACnB,MAAM;AAaR;AAMA,MAAM,YAAY;AAAA,EAChB,MAAM;AAiBR;AAEA,MAAM,wBAAwB;AAAA,EAC5B,MAAM;AAiBR;AAEA,MAAM,WAAW;AAAA,EACf,MAAM;AAiBR;AAEA,MAAM,iBAAiB;AAAA,EACrB,MAAM;AAiBR;AAEO,MAAM,mBAAmB;AAAA,EAC9B,wBAAwB;AAAA,EACxB,4BAA4B;AAAA,EAC5B,iBAAiB;AAAA,EACjB,sBAAsB;AAAA,EACtB,0BAA0B;AAAA,EAC1B,OAAO;AAAA,EACP,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,cAAc;AAAA,EAEd,UAAU;AAAA,EACV,sBAAsB;AAAA,EAEtB,SAAS;AAAA,EAET,eAAe;AACjB;AAcO,MAAM,4DAA4C,IAAY;AAAA,EACnE,wBAAwB;AAAA,EACxB,4BAA4B;AAAA,EAC5B,iBAAiB;AAAA,EACjB,sBAAsB;AAAA,EACtB,0BAA0B;AAAA,EAC1B,OAAO;AAAA,EACP,UAAU;AAAA,EACV,sBAAsB;AAAA,EACtB,SAAS;AACX,CAAC;AAKM,MAAM,oBAAoB,CAAC,aAAa,IAAI;AAKnD,MAAM,WAAW;AAAA,EACf,MAAM;AAKR;AAKA,MAAM,WAAW;AAAA,EACf,MAAM;AAKR;AAEA,MAAM,oBAAoB;AAAA,EACxB,MAAM;AAOR;AAEA,MAAM,0BAA0B;AAAA,EAC9B,MAAM;AAOR;AAEO,MAAM,kBAAkB,CAAC,SAAS,IAAI;AAEtC,MAAM,4BAA4B,CAAC,SAAS,IAAI;AAEhD,MAAM,uBAAuB;AAAA,EAClC,kBAAkB;AAAA,EAClB,wBAAwB;AAC1B;"}
+{"version":3,"file":"model-meta.js","sources":["../../src/model-meta.ts"],"sourcesContent":["/**\n * Model metadata interface for documentation and type inference\n */\ninterface ModelMeta {\n  name: string\n  supports: {\n    input: Array<'text' | 'image' | 'audio' | 'video' | 'document'>\n    output: Array<'text' | 'image' | 'audio' | 'video'>\n    capabilities?: Array<'reasoning' | 'tool_calling' | 'structured_outputs'>\n    tools?: ReadonlyArray<never>\n  }\n  max_input_tokens?: number\n  max_output_tokens?: number\n  context_window?: number\n  knowledge_cutoff?: string\n  pricing?: {\n    input: {\n      normal: number\n      cached?: number\n    }\n    output: {\n      normal: number\n    }\n  }\n}\n\nconst GROK_4_1_FAST_REASONING = {\n  name: 'grok-4-1-fast-reasoning',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.05,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_1_FAST_NON_REASONING = {\n  name: 'grok-4-1-fast-non-reasoning',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.05,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_CODE_FAST_1 = {\n  name: 'grok-code-fast-1',\n  context_window: 256_000,\n  supports: {\n    input: ['text'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.02,\n    },\n    output: {\n      normal: 1.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_FAST_REASONING = {\n  name: 'grok-4-fast-reasoning',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.05,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_FAST_NON_REASONING = {\n  name: 'grok-4-fast-non-reasoning',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.2,\n      cached: 0.05,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4 = {\n  name: 'grok-4',\n  context_window: 256_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 3,\n      cached: 0.75,\n    },\n    output: {\n      normal: 15,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_3_MINI = {\n  name: 'grok-3-mini',\n  context_window: 131_072,\n  supports: {\n    input: ['text'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 0.3,\n      cached: 0.075,\n    },\n    output: {\n      normal: 0.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_3 = {\n  name: 'grok-3',\n  context_window: 131_072,\n  supports: {\n    input: ['text'],\n    output: ['text'],\n    capabilities: ['structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 3,\n      cached: 0.75,\n    },\n    output: {\n      normal: 15,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_2_VISION = {\n  name: 'grok-2-vision-1212',\n  context_window: 32_768,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 2,\n    },\n    output: {\n      normal: 10,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_2_IMAGE = {\n  name: 'grok-2-image-1212',\n  supports: {\n    input: ['text'],\n    output: ['image'],\n  },\n  pricing: {\n    input: {\n      normal: 0.07,\n    },\n    output: {\n      normal: 0.07,\n    },\n  },\n} as const satisfies ModelMeta\n\n// Imagine API image models. Pricing is per generated image (output only).\nconst GROK_IMAGINE_IMAGE = {\n  name: 'grok-imagine-image',\n  supports: {\n    input: ['text', 'image'],\n    output: ['image'],\n  },\n  pricing: {\n    input: {\n      normal: 0,\n    },\n    output: {\n      normal: 0.02,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_IMAGINE_IMAGE_QUALITY = {\n  name: 'grok-imagine-image-quality',\n  supports: {\n    input: ['text', 'image'],\n    output: ['image'],\n  },\n  pricing: {\n    input: {\n      normal: 0,\n    },\n    output: {\n      normal: 0.05,\n    },\n  },\n} as const satisfies ModelMeta\n\n/**\n * Grok Chat Models\n * Based on xAI's available models as of 2025\n */\nconst GROK_4_20 = {\n  name: 'grok-4.20',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image', 'document'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 2,\n      cached: 0.2,\n    },\n    output: {\n      normal: 6,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_20_MULTI_AGENT = {\n  name: 'grok-4.20-multi-agent',\n  context_window: 2_000_000,\n  supports: {\n    input: ['text', 'image', 'document'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [] as const,\n  },\n  pricing: {\n    input: {\n      normal: 2,\n      cached: 0.2,\n    },\n    output: {\n      normal: 6,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_4_3 = {\n  name: 'grok-4.3',\n  context_window: 1_000_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [],\n  },\n  pricing: {\n    input: {\n      normal: 1.25,\n      cached: 0.2,\n    },\n    output: {\n      normal: 2.5,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_BUILD_0_1 = {\n  name: 'grok-build-0.1',\n  context_window: 256_000,\n  supports: {\n    input: ['text', 'image'],\n    output: ['text'],\n    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],\n    tools: [],\n  },\n  pricing: {\n    input: {\n      normal: 1,\n      cached: 0.2,\n    },\n    output: {\n      normal: 2,\n    },\n  },\n} as const satisfies ModelMeta\n\nexport const GROK_CHAT_MODELS = [\n  GROK_4_1_FAST_REASONING.name,\n  GROK_4_1_FAST_NON_REASONING.name,\n  GROK_CODE_FAST_1.name,\n  GROK_4_FAST_REASONING.name,\n  GROK_4_FAST_NON_REASONING.name,\n  GROK_4.name,\n  GROK_3.name,\n  GROK_3_MINI.name,\n  GROK_2_VISION.name,\n\n  GROK_4_20.name,\n  GROK_4_20_MULTI_AGENT.name,\n\n  GROK_4_3.name,\n\n  GROK_BUILD_0_1.name,\n] as const\n\n/**\n * Grok models that support combining `tools` + `response_format: json_schema`\n * in a single streaming Chat Completions request (per issue #605). xAI\n * docs gate this to the Grok 4 family — Grok 2 / 3 reject the\n * combination. Grok 2 image generation is not a chat model, omitted.\n *\n * Note: Grok streams tool-call arguments atomically (not token-streamed)\n * per the issue's source matrix; partial-JSON tool-arg parsing should be\n * skipped for Grok specifically. That's a separate adapter concern from\n * this set — the set only gates whether the engine takes the native\n * combined path vs the legacy finalization path.\n */\nexport const GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS = new Set<string>([\n  GROK_4_1_FAST_REASONING.name,\n  GROK_4_1_FAST_NON_REASONING.name,\n  GROK_CODE_FAST_1.name,\n  GROK_4_FAST_REASONING.name,\n  GROK_4_FAST_NON_REASONING.name,\n  GROK_4.name,\n  GROK_4_20.name,\n  GROK_4_20_MULTI_AGENT.name,\n  GROK_4_3.name,\n])\n\n/**\n * Grok Image Generation Models\n */\nexport const GROK_IMAGE_MODELS = [\n  GROK_2_IMAGE.name,\n  GROK_IMAGINE_IMAGE.name,\n  GROK_IMAGINE_IMAGE_QUALITY.name,\n] as const\n\n// xAI's `/v1/tts` endpoint is endpoint-addressed and does not take a `model`\n// parameter. This synthetic identifier satisfies the SDK's `TTSOptions.model`\n// contract and provides a stable value for logging and fixture matching.\nconst GROK_TTS = {\n  name: 'grok-tts',\n  supports: {\n    input: ['text'],\n    output: ['audio'],\n  },\n} as const satisfies ModelMeta\n\n// xAI's `/v1/stt` endpoint is endpoint-addressed and does not take a `model`\n// parameter. This synthetic identifier satisfies the SDK's\n// `TranscriptionOptions.model` contract.\nconst GROK_STT = {\n  name: 'grok-stt',\n  supports: {\n    input: ['audio'],\n    output: ['text'],\n  },\n} as const satisfies ModelMeta\n\nconst GROK_VOICE_FAST_1 = {\n  name: 'grok-voice-fast-1.0',\n  supports: {\n    input: ['audio', 'text'],\n    output: ['audio', 'text'],\n    capabilities: ['tool_calling'],\n    tools: [] as const,\n  },\n} as const satisfies ModelMeta\n\nconst GROK_VOICE_THINK_FAST_1 = {\n  name: 'grok-voice-think-fast-1.0',\n  supports: {\n    input: ['audio', 'text'],\n    output: ['audio', 'text'],\n    capabilities: ['reasoning', 'tool_calling'],\n    tools: [] as const,\n  },\n} as const satisfies ModelMeta\n\nexport const GROK_TTS_MODELS = [GROK_TTS.name] as const\n\nexport const GROK_TRANSCRIPTION_MODELS = [GROK_STT.name] as const\n\nexport const GROK_REALTIME_MODELS = [\n  GROK_VOICE_FAST_1.name,\n  GROK_VOICE_THINK_FAST_1.name,\n] as const\n\nexport type GrokChatModel = (typeof GROK_CHAT_MODELS)[number]\nexport type GrokImageModel = (typeof GROK_IMAGE_MODELS)[number]\nexport type GrokTTSModel = (typeof GROK_TTS_MODELS)[number]\nexport type GrokTranscriptionModel = (typeof GROK_TRANSCRIPTION_MODELS)[number]\nexport type GrokRealtimeModel = (typeof GROK_REALTIME_MODELS)[number]\n\n/**\n * Type-only map from Grok chat model name to its supported input modalities.\n * Used for type inference when constructing multimodal messages.\n */\nexport type GrokModelInputModalitiesByName = {\n  [GROK_4_1_FAST_REASONING.name]: typeof GROK_4_1_FAST_REASONING.supports.input\n  [GROK_4_1_FAST_NON_REASONING.name]: typeof GROK_4_1_FAST_NON_REASONING.supports.input\n  [GROK_CODE_FAST_1.name]: typeof GROK_CODE_FAST_1.supports.input\n  [GROK_4_FAST_REASONING.name]: typeof GROK_4_FAST_REASONING.supports.input\n  [GROK_4_FAST_NON_REASONING.name]: typeof GROK_4_FAST_NON_REASONING.supports.input\n  [GROK_4.name]: typeof GROK_4.supports.input\n  [GROK_3.name]: typeof GROK_3.supports.input\n  [GROK_3_MINI.name]: typeof GROK_3_MINI.supports.input\n  [GROK_2_VISION.name]: typeof GROK_2_VISION.supports.input\n  [GROK_4_20.name]: typeof GROK_4_20.supports.input\n  [GROK_4_20_MULTI_AGENT.name]: typeof GROK_4_20_MULTI_AGENT.supports.input\n  [GROK_4_3.name]: typeof GROK_4_3.supports.input\n  [GROK_BUILD_0_1.name]: typeof GROK_BUILD_0_1.supports.input\n}\n\n/**\n * Type-only map from Grok chat model name to its provider options type.\n * Since Grok uses OpenAI-compatible API, we reuse OpenAI provider options.\n */\nexport type GrokChatModelProviderOptionsByName = {\n  [K in (typeof GROK_CHAT_MODELS)[number]]: GrokProviderOptions\n}\n\n/**\n * Type-only map from Grok chat model name to its supported provider tools.\n * Grok exposes no provider-specific tool factories, so every model gets an\n * empty tuple. This ensures that passing an Anthropic/OpenAI ProviderTool to\n * a Grok adapter produces a compile-time type error.\n */\nexport type GrokChatModelToolCapabilitiesByName = {\n  [GROK_4_1_FAST_REASONING.name]: typeof GROK_4_1_FAST_REASONING.supports.tools\n  [GROK_4_1_FAST_NON_REASONING.name]: typeof GROK_4_1_FAST_NON_REASONING.supports.tools\n  [GROK_CODE_FAST_1.name]: typeof GROK_CODE_FAST_1.supports.tools\n  [GROK_4_FAST_REASONING.name]: typeof GROK_4_FAST_REASONING.supports.tools\n  [GROK_4_FAST_NON_REASONING.name]: typeof GROK_4_FAST_NON_REASONING.supports.tools\n  [GROK_4.name]: typeof GROK_4.supports.tools\n  [GROK_3.name]: typeof GROK_3.supports.tools\n  [GROK_3_MINI.name]: typeof GROK_3_MINI.supports.tools\n  [GROK_2_VISION.name]: typeof GROK_2_VISION.supports.tools\n  [GROK_4_20.name]: typeof GROK_4_20.supports.tools\n  [GROK_4_20_MULTI_AGENT.name]: typeof GROK_4_20_MULTI_AGENT.supports.tools\n}\n\n/**\n * Grok-specific provider options\n * Based on OpenAI-compatible API options\n */\nexport interface GrokProviderOptions {\n  /** Temperature for response generation (0-2) */\n  temperature?: number\n  /** Maximum tokens in the response */\n  max_tokens?: number\n  /** Top-p sampling parameter */\n  top_p?: number\n  /** Frequency penalty (-2.0 to 2.0) */\n  frequency_penalty?: number\n  /** Presence penalty (-2.0 to 2.0) */\n  presence_penalty?: number\n  /** Stop sequences */\n  stop?: string | Array<string>\n  /** A unique identifier representing your end-user */\n  user?: string\n}\n\n// ===========================\n// Type Resolution Helpers\n// ===========================\n\n/**\n * Resolve provider options for a specific model.\n * If the model has explicit options in the map, use those; otherwise use base options.\n */\nexport type ResolveProviderOptions<TModel extends string> =\n  TModel extends keyof GrokChatModelProviderOptionsByName\n    ? GrokChatModelProviderOptionsByName[TModel]\n    : GrokProviderOptions\n\n/**\n * Resolve input modalities for a specific model.\n * If the model has explicit modalities in the map, use those; otherwise use text only.\n */\nexport type ResolveInputModalities<TModel extends string> =\n  TModel extends keyof GrokModelInputModalitiesByName\n    ? GrokModelInputModalitiesByName[TModel]\n    : readonly ['text']\n"],"names":[],"mappings":"AA0BA,MAAM,0BAA0B;AAAA,EAC9B,MAAM;AAiBR;AAEA,MAAM,8BAA8B;AAAA,EAClC,MAAM;AAiBR;AAEA,MAAM,mBAAmB;AAAA,EACvB,MAAM;AAiBR;AAEA,MAAM,wBAAwB;AAAA,EAC5B,MAAM;AAiBR;AAEA,MAAM,4BAA4B;AAAA,EAChC,MAAM;AAiBR;AAEA,MAAM,SAAS;AAAA,EACb,MAAM;AAiBR;AAEA,MAAM,cAAc;AAAA,EAClB,MAAM;AAiBR;AAEA,MAAM,SAAS;AAAA,EACb,MAAM;AAiBR;AAEA,MAAM,gBAAgB;AAAA,EACpB,MAAM;AAgBR;AAEA,MAAM,eAAe;AAAA,EACnB,MAAM;AAaR;AAGA,MAAM,qBAAqB;AAAA,EACzB,MAAM;AAaR;AAEA,MAAM,6BAA6B;AAAA,EACjC,MAAM;AAaR;AAMA,MAAM,YAAY;AAAA,EAChB,MAAM;AAiBR;AAEA,MAAM,wBAAwB;AAAA,EAC5B,MAAM;AAiBR;AAEA,MAAM,WAAW;AAAA,EACf,MAAM;AAiBR;AAEA,MAAM,iBAAiB;AAAA,EACrB,MAAM;AAiBR;AAEO,MAAM,mBAAmB;AAAA,EAC9B,wBAAwB;AAAA,EACxB,4BAA4B;AAAA,EAC5B,iBAAiB;AAAA,EACjB,sBAAsB;AAAA,EACtB,0BAA0B;AAAA,EAC1B,OAAO;AAAA,EACP,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,cAAc;AAAA,EAEd,UAAU;AAAA,EACV,sBAAsB;AAAA,EAEtB,SAAS;AAAA,EAET,eAAe;AACjB;AAcO,MAAM,4DAA4C,IAAY;AAAA,EACnE,wBAAwB;AAAA,EACxB,4BAA4B;AAAA,EAC5B,iBAAiB;AAAA,EACjB,sBAAsB;AAAA,EACtB,0BAA0B;AAAA,EAC1B,OAAO;AAAA,EACP,UAAU;AAAA,EACV,sBAAsB;AAAA,EACtB,SAAS;AACX,CAAC;AAKM,MAAM,oBAAoB;AAAA,EAC/B,aAAa;AAAA,EACb,mBAAmB;AAAA,EACnB,2BAA2B;AAC7B;AAKA,MAAM,WAAW;AAAA,EACf,MAAM;AAKR;AAKA,MAAM,WAAW;AAAA,EACf,MAAM;AAKR;AAEA,MAAM,oBAAoB;AAAA,EACxB,MAAM;AAOR;AAEA,MAAM,0BAA0B;AAAA,EAC9B,MAAM;AAOR;AAEO,MAAM,kBAAkB,CAAC,SAAS,IAAI;AAEtC,MAAM,4BAA4B,CAAC,SAAS,IAAI;AAEhD,MAAM,uBAAuB;AAAA,EAClC,kBAAkB;AAAA,EAClB,wBAAwB;AAC1B;"}

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "@tanstack/ai-grok",
-  "version": "0.11.3",
+  "version": "0.12.1",
   "description": "xAI Grok adapter for TanStack AI chat, image generation, realtime, and structured outputs.",
-  "author": "",
+  "author": "Tanner Linsley",
   "license": "MIT",
+  "homepage": "https://tanstack.com/ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TanStack/ai.git",
     "directory": "packages/ai-grok"
   },
+  "bugs": {
+    "url": "https://github.com/TanStack/ai/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
   "type": "module",
   "module": "./dist/esm/index.js",
   "types": "./dist/esm/index.d.ts",
@@ -42,18 +50,18 @@
   ],
   "dependencies": {
     "openai": "^6.41.0",
-    "@tanstack/ai-utils": "0.2.1",
-    "@tanstack/openai-base": "0.8.2"
+    "@tanstack/ai-utils": "0.2.2",
+    "@tanstack/openai-base": "0.8.6"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",
     "vite": "^7.3.3",
-    "@tanstack/ai": "0.29.0",
-    "@tanstack/ai-client": "0.17.0"
+    "@tanstack/ai": "0.32.0",
+    "@tanstack/ai-client": "0.18.0"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@tanstack/ai": "^0.29.0"
+    "@tanstack/ai": "^0.32.0"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/image.ts

@@ -1,10 +1,13 @@
 import OpenAI from 'openai'
+import { resolveMediaPrompt } from '@tanstack/ai'
 import { BaseImageAdapter } from '@tanstack/ai/adapters'
 import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
 import { buildImagesUsage } from '@tanstack/openai-base'
 import { generateId } from '@tanstack/ai-utils'
 import { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'
 import {
+  isGrokImagineImageModel,
+  parseGrokImagineSize,
   validateImageSize,
   validateNumberOfImages,
   validatePrompt,
@@ -13,10 +16,14 @@ import type {
   GeneratedImage,
   ImageGenerationOptions,
   ImageGenerationResult,
+  ImagePart,
+  MediaInputMetadata,
+  ResolvedMediaPrompt,
 } from '@tanstack/ai'
 import type OpenAI_SDK from 'openai'
 import type { GrokImageModel } from '../model-meta'
 import type {
+  GrokImageModelInputModalitiesByName,
   GrokImageModelProviderOptionsByName,
   GrokImageModelSizeByName,
   GrokImageProviderOptions,
@@ -28,15 +35,58 @@ import type { GrokClientConfig } from '../utils'
  */
 export interface GrokImageConfig extends GrokClientConfig {}
 
+/** Maximum source images accepted by xAI's image edit endpoint. */
+const MAX_EDIT_IMAGES = 3
+
+/**
+ * Maps the generic `size` option onto Imagine API parameters: the
+ * "aspectRatio_resolution" template ("16:9_2k") splits into `aspect_ratio`
+ * and optional `resolution` request fields.
+ */
+function imagineSizeParams(size: string | undefined): {
+  aspect_ratio?: string
+  resolution?: string
+} {
+  if (!size) return {}
+  const parsed = parseGrokImagineSize(size)
+  if (!parsed) return {}
+  return {
+    aspect_ratio: parsed.aspectRatio,
+    ...(parsed.resolution !== undefined && { resolution: parsed.resolution }),
+  }
+}
+
+/**
+ * Convert a TanStack ImagePart to the URL string accepted by xAI's edit
+ * endpoint: public URLs pass through (fetched by xAI's servers), data
+ * sources become base64 data URIs.
+ */
+function imagePartToUrl(part: ImagePart<MediaInputMetadata>): string {
+  if (part.source.type === 'url') return part.source.value
+  return `data:${part.source.mimeType};base64,${part.source.value}`
+}
+
+/** Response shape of xAI's `/v1/images/edits` endpoint. */
+interface GrokImageEditResponse {
+  data?: Array<{
+    url?: string | null
+    b64_json?: string | null
+    mime_type?: string
+  }>
+}
+
 /**
  * Grok Image Generation Adapter
  *
  * Tree-shakeable adapter for Grok image generation functionality.
- * Supports grok-2-image-1212 model.
+ * Supports the legacy grok-2-image-1212 model (text-to-image via the
+ * OpenAI-compat endpoint) and the grok-imagine image models, which also
+ * accept image prompt parts for image-conditioned generation via xAI's
+ * `/v1/images/edits` endpoint (up to 3 source images).
  *
  * Features:
  * - Model-specific type-safe provider options
- * - Size validation per model
+ * - Size / aspect-ratio validation per model
  * - Number of images validation
  */
 export class GrokImageAdapter<
@@ -45,36 +95,67 @@ export class GrokImageAdapter<
   TModel,
   GrokImageProviderOptions,
   GrokImageModelProviderOptionsByName,
-  GrokImageModelSizeByName
+  GrokImageModelSizeByName,
+  GrokImageModelInputModalitiesByName
 > {
   override readonly kind = 'image' as const
   readonly name = 'grok' as const
 
   protected client: OpenAI
+  private readonly clientConfig: GrokImageConfig
 
   constructor(config: GrokImageConfig, model: TModel) {
     super(model, {})
-    this.client = new OpenAI(withGrokDefaults(config))
+    this.clientConfig = withGrokDefaults(config)
+    this.client = new OpenAI(this.clientConfig)
   }
 
   async generateImages(
     options: ImageGenerationOptions<GrokImageProviderOptions>,
   ): Promise<ImageGenerationResult> {
-    const { model, prompt, numberOfImages, size, modelOptions } = options
+    const { model, numberOfImages, size, modelOptions } = options
+
+    const resolved = resolveMediaPrompt(options.prompt)
+    const prompt = resolved.text
+
+    if (resolved.videos.length > 0 || resolved.audios.length > 0) {
+      throw new Error(
+        `grok.generateImages does not support video / audio prompt parts on model ${model}.`,
+      )
+    }
+
+    if (resolved.images.length > 0) {
+      if (!isGrokImagineImageModel(model)) {
+        throw new Error(
+          `grok: model "${model}" does not support image prompt parts. ` +
+            `Image-conditioned generation requires an Imagine API model ` +
+            `('grok-imagine-image' or 'grok-imagine-image-quality').`,
+        )
+      }
+      return await this.editImages(options, resolved)
+    }
 
     validatePrompt({ prompt, model })
     validateImageSize(model, size)
     validateNumberOfImages(model, numberOfImages)
 
-    const resolvedSize = size as OpenAI_SDK.Images.ImageGenerateParams['size']
-    const request: OpenAI_SDK.Images.ImageGenerateParamsNonStreaming = {
+    // grok-imagine models are aspect-ratio sized: the generic `size` option
+    // carries an "aspectRatio_resolution" template (e.g. '16:9_2k', like
+    // Gemini native image models) and maps to the Imagine API's
+    // `aspect_ratio` / `resolution` parameters instead of OpenAI-style `size`.
+    const isImagine = isGrokImagineImageModel(model)
+    const request = {
       model,
       prompt,
       n: numberOfImages ?? 1,
-      ...(resolvedSize !== undefined && { size: resolvedSize }),
+      ...(isImagine
+        ? imagineSizeParams(size)
+        : size !== undefined && {
+            size: size,
+          }),
       stream: false,
       ...modelOptions,
-    }
+    } as OpenAI_SDK.Images.ImageGenerateParamsNonStreaming
 
     try {
       options.logger.request(
@@ -122,6 +203,106 @@ export class GrokImageAdapter<
       throw error
     }
   }
+
+  /**
+   * Image-conditioned generation via xAI's Imagine API.
+   *
+   * The `/v1/images/edits` endpoint takes `application/json` (the OpenAI
+   * SDK's `images.edit()` sends `multipart/form-data`, which xAI rejects),
+   * so this path issues the request directly. One input is sent as
+   * `image: { url }`; multiple inputs (up to 3) as `images: [{ url }, ...]`,
+   * addressed by xAI in the order they are sent. The prompt text is sent
+   * verbatim — no referencing markers are injected.
+   */
+  private async editImages(
+    options: ImageGenerationOptions<GrokImageProviderOptions>,
+    resolved: ResolvedMediaPrompt,
+  ): Promise<ImageGenerationResult> {
+    const { model, numberOfImages, size, modelOptions, logger } = options
+    const prompt = resolved.text
+    const imageInputs = resolved.images
+
+    const unsupportedRole = imageInputs.find(
+      (part) =>
+        part.metadata?.role === 'mask' || part.metadata?.role === 'control',
+    )
+    if (unsupportedRole) {
+      throw new Error(
+        `grok: the Imagine API has no ${unsupportedRole.metadata?.role} input; ` +
+          `only source/reference images are supported.`,
+      )
+    }
+    if (imageInputs.length > MAX_EDIT_IMAGES) {
+      throw new Error(
+        `grok: model "${model}" accepts at most ${MAX_EDIT_IMAGES} source images; received ${imageInputs.length}.`,
+      )
+    }
+
+    validatePrompt({ prompt, model })
+    validateImageSize(model, size)
+    validateNumberOfImages(model, numberOfImages)
+
+    const urls = imageInputs.map((part) => imagePartToUrl(part))
+    const request: Record<string, unknown> = {
+      model,
+      prompt,
+      ...(urls.length === 1
+        ? { image: { url: urls[0] } }
+        : { images: urls.map((url) => ({ url })) }),
+      ...(numberOfImages !== undefined && { n: numberOfImages }),
+      ...imagineSizeParams(size),
+      ...modelOptions,
+    }
+
+    try {
+      logger.request(
+        `activity=image provider=${this.name} model=${model} edit images=${urls.length}`,
+        { provider: this.name, model },
+      )
+
+      const response = await fetch(
+        `${this.clientConfig.baseURL}/images/edits`,
+        {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this.clientConfig.apiKey}`,
+          },
+          body: JSON.stringify(request),
+        },
+      )
+      if (!response.ok) {
+        const body = await response.text()
+        throw new Error(
+          `grok: image edit request failed (${response.status} ${response.statusText}): ${body}`,
+        )
+      }
+
+      const result = (await response.json()) as GrokImageEditResponse
+      const images: Array<GeneratedImage> = (result.data ?? []).flatMap(
+        (item): Array<GeneratedImage> => {
+          if (item.b64_json) return [{ b64Json: item.b64_json }]
+          if (item.url) return [{ url: item.url }]
+          return []
+        },
+      )
+      if (images.length === 0) {
+        throw new Error('grok: image edit response contained no images')
+      }
+
+      return {
+        id: generateId(this.name),
+        model,
+        images,
+      }
+    } catch (error: unknown) {
+      logger.errors(`${this.name}.generateImages fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.generateImages failed`),
+        source: `${this.name}.generateImages`,
+      })
+      throw error
+    }
+  }
 }
 
 /**

package/src/image/image-provider-options.ts

@@ -10,6 +10,84 @@
  */
 export type GrokImageSize = '1024x1024' | '1536x1024' | '1024x1536'
 
+/**
+ * Aspect ratios accepted by the grok-imagine image models.
+ */
+export type GrokImagineAspectRatio =
+  | '1:1'
+  | '3:4'
+  | '4:3'
+  | '9:16'
+  | '16:9'
+  | '2:3'
+  | '3:2'
+  | '9:19.5'
+  | '19.5:9'
+  | '9:20'
+  | '20:9'
+  | '1:2'
+  | '2:1'
+  | 'auto'
+
+/**
+ * Resolution tiers for the grok-imagine image models.
+ */
+export type GrokImagineResolution = '1k' | '2k'
+
+/**
+ * Size strings for grok-imagine image models. The Imagine API is
+ * aspect-ratio based rather than pixel-size based; like Gemini's native
+ * image models, the generic `size` option uses an
+ * `aspectRatio_resolution` template ("16:9_2k") — the resolution suffix is
+ * optional ("16:9" uses the API default of 1k).
+ */
+export type GrokImagineImageSize =
+  | GrokImagineAspectRatio
+  | `${GrokImagineAspectRatio}_${GrokImagineResolution}`
+
+const GROK_IMAGINE_ASPECT_RATIOS: ReadonlyArray<string> = [
+  '1:1',
+  '3:4',
+  '4:3',
+  '9:16',
+  '16:9',
+  '2:3',
+  '3:2',
+  '9:19.5',
+  '19.5:9',
+  '9:20',
+  '20:9',
+  '1:2',
+  '2:1',
+  'auto',
+]
+
+const GROK_IMAGINE_RESOLUTIONS: ReadonlyArray<string> = ['1k', '2k']
+
+/**
+ * Models served by xAI's Imagine API. They are aspect-ratio sized and
+ * support image-conditioned generation via `/v1/images/edits`; the legacy
+ * grok-2-image-1212 model is pixel-sized and text-to-image only.
+ */
+export function isGrokImagineImageModel(model: string): boolean {
+  return model.startsWith('grok-imagine-image')
+}
+
+/**
+ * Parses a grok-imagine size string into its components.
+ * Format: "aspectRatio" or "aspectRatio_resolution",
+ * e.g. "16:9_2k" → { aspectRatio: "16:9", resolution: "2k" }.
+ * Returns undefined when the string doesn't match the template.
+ */
+export function parseGrokImagineSize(
+  size: string,
+): { aspectRatio: string; resolution?: string } | undefined {
+  const match = size.match(/^([\d.]+:[\d.]+|auto)(?:_(.+))?$/)
+  const [, aspectRatio, resolution] = match ?? []
+  if (aspectRatio === undefined) return undefined
+  return { aspectRatio, ...(resolution !== undefined && { resolution }) }
+}
+
 /**
  * Base provider options for Grok image models
  */
@@ -39,11 +117,37 @@ export interface GrokImageProviderOptions extends GrokImageBaseProviderOptions {
   response_format?: 'url' | 'b64_json'
 }
 
+/**
+ * Provider options for the grok-imagine image models (generation and
+ * image-conditioned editing via xAI's Imagine API).
+ */
+export interface GrokImagineImageProviderOptions extends GrokImageBaseProviderOptions {
+  /**
+   * The format in which generated images are returned.
+   * @default 'url'
+   */
+  response_format?: 'url' | 'b64_json'
+
+  /**
+   * Output resolution.
+   * @default '1k'
+   */
+  resolution?: '1k' | '2k'
+
+  /**
+   * Processing tier for the request.
+   * @default 'default'
+   */
+  service_tier?: 'default' | 'priority'
+}
+
 /**
  * Type-only map from model name to its specific provider options.
  */
 export type GrokImageModelProviderOptionsByName = {
   'grok-2-image-1212': GrokImageProviderOptions
+  'grok-imagine-image': GrokImagineImageProviderOptions
+  'grok-imagine-image-quality': GrokImagineImageProviderOptions
 }
 
 /**
@@ -51,6 +155,19 @@ export type GrokImageModelProviderOptionsByName = {
  */
 export type GrokImageModelSizeByName = {
   'grok-2-image-1212': GrokImageSize
+  'grok-imagine-image': GrokImagineImageSize
+  'grok-imagine-image-quality': GrokImagineImageSize
+}
+
+/**
+ * Per-model prompt input modalities. Imagine API models accept image parts
+ * in the prompt (routed to `/v1/images/edits`, up to 3 images, addressed by
+ * xAI in request order); grok-2-image is text-to-image only.
+ */
+export type GrokImageModelInputModalitiesByName = {
+  'grok-2-image-1212': readonly []
+  'grok-imagine-image': readonly ['image']
+  'grok-imagine-image-quality': readonly ['image']
 }
 
 /**
@@ -71,6 +188,23 @@ export function validateImageSize(
 ): void {
   if (!size) return
 
+  if (isGrokImagineImageModel(model)) {
+    const parsed = parseGrokImagineSize(size)
+    if (
+      !parsed ||
+      !GROK_IMAGINE_ASPECT_RATIOS.includes(parsed.aspectRatio) ||
+      (parsed.resolution !== undefined &&
+        !GROK_IMAGINE_RESOLUTIONS.includes(parsed.resolution))
+    ) {
+      throw new Error(
+        `Size "${size}" is not supported by model "${model}". ` +
+          `Expected an aspect ratio (${GROK_IMAGINE_ASPECT_RATIOS.join(', ')}) ` +
+          `optionally suffixed with a resolution ("16:9_2k"; resolutions: ${GROK_IMAGINE_RESOLUTIONS.join(', ')}).`,
+      )
+    }
+    return
+  }
+
   const validSizes: Record<string, Array<string>> = {
     'grok-2-image-1212': ['1024x1024', '1536x1024', '1024x1536'],
   }

package/src/model-meta.ts

@@ -219,6 +219,39 @@ const GROK_2_IMAGE = {
   },
 } as const satisfies ModelMeta
 
+// Imagine API image models. Pricing is per generated image (output only).
+const GROK_IMAGINE_IMAGE = {
+  name: 'grok-imagine-image',
+  supports: {
+    input: ['text', 'image'],
+    output: ['image'],
+  },
+  pricing: {
+    input: {
+      normal: 0,
+    },
+    output: {
+      normal: 0.02,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_IMAGINE_IMAGE_QUALITY = {
+  name: 'grok-imagine-image-quality',
+  supports: {
+    input: ['text', 'image'],
+    output: ['image'],
+  },
+  pricing: {
+    input: {
+      normal: 0,
+    },
+    output: {
+      normal: 0.05,
+    },
+  },
+} as const satisfies ModelMeta
+
 /**
  * Grok Chat Models
  * Based on xAI's available models as of 2025
@@ -349,7 +382,11 @@ export const GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS = new Set<string>([
 /**
  * Grok Image Generation Models
  */
-export const GROK_IMAGE_MODELS = [GROK_2_IMAGE.name] as const
+export const GROK_IMAGE_MODELS = [
+  GROK_2_IMAGE.name,
+  GROK_IMAGINE_IMAGE.name,
+  GROK_IMAGINE_IMAGE_QUALITY.name,
+] as const
 
 // xAI's `/v1/tts` endpoint is endpoint-addressed and does not take a `model`
 // parameter. This synthetic identifier satisfies the SDK's `TTSOptions.model`