@tanstack/ai-grok 0.6.8 → 0.7.1

package/dist/esm/adapters/image.js

@@ -3,7 +3,7 @@ import { createGrokClient, generateId, getGrokApiKeyFromEnv } from "../utils/cli
 import { validatePrompt, validateImageSize, validateNumberOfImages } from "../image/image-provider-options.js";
 class GrokImageAdapter extends BaseImageAdapter {
   constructor(config, model) {
-    super({}, model);
+    super(model, {});
     this.kind = "image";
     this.name = "grok";
     this.client = createGrokClient(config);
@@ -35,19 +35,26 @@ class GrokImageAdapter extends BaseImageAdapter {
   buildRequest(options) {
     const { model, prompt, numberOfImages, size, modelOptions } = options;
     return {
+      ...modelOptions,
       model,
       prompt,
       n: numberOfImages ?? 1,
-      size,
-      ...modelOptions
+      size
     };
   }
   transformResponse(model, response) {
-    const images = (response.data ?? []).map((item) => ({
-      b64Json: item.b64_json,
-      url: item.url,
-      revisedPrompt: item.revised_prompt
-    }));
+    const images = (response.data ?? []).flatMap(
+      (item) => {
+        const revisedPrompt = item.revised_prompt;
+        if (item.b64_json) {
+          return [{ b64Json: item.b64_json, revisedPrompt }];
+        }
+        if (item.url) {
+          return [{ url: item.url, revisedPrompt }];
+        }
+        return [];
+      }
+    );
     return {
       id: generateId(this.name),
       model,

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

@@ -1 +1 @@
-{"version":3,"file":"image.js","sources":["../../../src/adapters/image.ts"],"sourcesContent":["import { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport { createGrokClient, generateId, getGrokApiKeyFromEnv } from '../utils'\nimport {\n  validateImageSize,\n  validateNumberOfImages,\n  validatePrompt,\n} from '../image/image-provider-options'\nimport type { GrokImageModel } from '../model-meta'\nimport type {\n  GrokImageModelProviderOptionsByName,\n  GrokImageModelSizeByName,\n  GrokImageProviderOptions,\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 { 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  readonly kind = 'image' as const\n  readonly name = 'grok' as const\n\n  private client: OpenAI_SDK\n\n  constructor(config: GrokImageConfig, model: TModel) {\n    super({}, model)\n    this.client = createGrokClient(config)\n  }\n\n  async generateImages(\n    options: ImageGenerationOptions<GrokImageProviderOptions>,\n  ): Promise<ImageGenerationResult> {\n    const { model, prompt, numberOfImages, size, logger } = options\n\n    logger.request(`activity=generateImage provider=grok model=${this.model}`, {\n      provider: 'grok',\n      model: this.model,\n    })\n\n    try {\n      // Validate inputs\n      validatePrompt({ prompt, model })\n      validateImageSize(model, size)\n      validateNumberOfImages(model, numberOfImages)\n\n      // Build request based on model type\n      const request = this.buildRequest(options)\n\n      const response = await this.client.images.generate({\n        ...request,\n        stream: false,\n      })\n\n      return this.transformResponse(model, response)\n    } catch (error) {\n      logger.errors('grok.generateImage fatal', {\n        error,\n        source: 'grok.generateImage',\n      })\n      throw error\n    }\n  }\n\n  private buildRequest(\n    options: ImageGenerationOptions<GrokImageProviderOptions>,\n  ): OpenAI_SDK.Images.ImageGenerateParams {\n    const { model, prompt, numberOfImages, size, modelOptions } = options\n\n    return {\n      model,\n      prompt,\n      n: numberOfImages ?? 1,\n      size: size as OpenAI_SDK.Images.ImageGenerateParams['size'],\n      ...modelOptions,\n    }\n  }\n\n  private transformResponse(\n    model: string,\n    response: OpenAI_SDK.Images.ImagesResponse,\n  ): ImageGenerationResult {\n    const images: Array<GeneratedImage> = (response.data ?? []).map((item) => ({\n      b64Json: item.b64_json,\n      url: item.url,\n      revisedPrompt: item.revised_prompt,\n    }))\n\n    return {\n      id: generateId(this.name),\n      model,\n      images,\n      usage: response.usage\n        ? {\n            inputTokens: response.usage.input_tokens,\n            outputTokens: response.usage.output_tokens,\n            totalTokens: response.usage.total_tokens,\n          }\n        : undefined,\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":";;;AAqCO,MAAM,yBAEH,iBAKR;AAAA,EAMA,YAAY,QAAyB,OAAe;AAClD,UAAM,CAAA,GAAI,KAAK;AANjB,SAAS,OAAO;AAChB,SAAS,OAAO;AAMd,SAAK,SAAS,iBAAiB,MAAM;AAAA,EACvC;AAAA,EAEA,MAAM,eACJ,SACgC;AAChC,UAAM,EAAE,OAAO,QAAQ,gBAAgB,MAAM,WAAW;AAExD,WAAO,QAAQ,8CAA8C,KAAK,KAAK,IAAI;AAAA,MACzE,UAAU;AAAA,MACV,OAAO,KAAK;AAAA,IAAA,CACb;AAED,QAAI;AAEF,qBAAe,EAAE,QAAQ,OAAO;AAChC,wBAAkB,OAAO,IAAI;AAC7B,6BAAuB,OAAO,cAAc;AAG5C,YAAM,UAAU,KAAK,aAAa,OAAO;AAEzC,YAAM,WAAW,MAAM,KAAK,OAAO,OAAO,SAAS;AAAA,QACjD,GAAG;AAAA,QACH,QAAQ;AAAA,MAAA,CACT;AAED,aAAO,KAAK,kBAAkB,OAAO,QAAQ;AAAA,IAC/C,SAAS,OAAO;AACd,aAAO,OAAO,4BAA4B;AAAA,QACxC;AAAA,QACA,QAAQ;AAAA,MAAA,CACT;AACD,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEQ,aACN,SACuC;AACvC,UAAM,EAAE,OAAO,QAAQ,gBAAgB,MAAM,iBAAiB;AAE9D,WAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,GAAG,kBAAkB;AAAA,MACrB;AAAA,MACA,GAAG;AAAA,IAAA;AAAA,EAEP;AAAA,EAEQ,kBACN,OACA,UACuB;AACvB,UAAM,UAAiC,SAAS,QAAQ,CAAA,GAAI,IAAI,CAAC,UAAU;AAAA,MACzE,SAAS,KAAK;AAAA,MACd,KAAK,KAAK;AAAA,MACV,eAAe,KAAK;AAAA,IAAA,EACpB;AAEF,WAAO;AAAA,MACL,IAAI,WAAW,KAAK,IAAI;AAAA,MACxB;AAAA,MACA;AAAA,MACA,OAAO,SAAS,QACZ;AAAA,QACE,aAAa,SAAS,MAAM;AAAA,QAC5B,cAAc,SAAS,MAAM;AAAA,QAC7B,aAAa,SAAS,MAAM;AAAA,MAAA,IAE9B;AAAA,IAAA;AAAA,EAER;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 { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport { createGrokClient, generateId, getGrokApiKeyFromEnv } from '../utils'\nimport {\n  validateImageSize,\n  validateNumberOfImages,\n  validatePrompt,\n} from '../image/image-provider-options'\nimport type { GrokImageModel } from '../model-meta'\nimport type {\n  GrokImageModelProviderOptionsByName,\n  GrokImageModelSizeByName,\n  GrokImageProviderOptions,\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 { 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  readonly kind = 'image' as const\n  readonly name = 'grok' as const\n\n  private client: OpenAI_SDK\n\n  constructor(config: GrokImageConfig, model: TModel) {\n    super(model, {})\n    this.client = createGrokClient(config)\n  }\n\n  async generateImages(\n    options: ImageGenerationOptions<GrokImageProviderOptions>,\n  ): Promise<ImageGenerationResult> {\n    const { model, prompt, numberOfImages, size, logger } = options\n\n    logger.request(`activity=generateImage provider=grok model=${this.model}`, {\n      provider: 'grok',\n      model: this.model,\n    })\n\n    try {\n      // Validate inputs\n      validatePrompt({ prompt, model })\n      validateImageSize(model, size)\n      validateNumberOfImages(model, numberOfImages)\n\n      // Build request based on model type\n      const request = this.buildRequest(options)\n\n      const response = await this.client.images.generate({\n        ...request,\n        stream: false,\n      })\n\n      return this.transformResponse(model, response)\n    } catch (error) {\n      logger.errors('grok.generateImage fatal', {\n        error,\n        source: 'grok.generateImage',\n      })\n      throw error\n    }\n  }\n\n  private buildRequest(\n    options: ImageGenerationOptions<GrokImageProviderOptions>,\n  ): OpenAI_SDK.Images.ImageGenerateParams {\n    const { model, prompt, numberOfImages, size, modelOptions } = options\n\n    // Spread modelOptions FIRST so explicit args (model, prompt, n, size) win\n    // and user-supplied modelOptions cannot silently override them.\n    return {\n      ...modelOptions,\n      model,\n      prompt,\n      n: numberOfImages ?? 1,\n      size: size as OpenAI_SDK.Images.ImageGenerateParams['size'],\n    }\n  }\n\n  private transformResponse(\n    model: string,\n    response: OpenAI_SDK.Images.ImagesResponse,\n  ): ImageGenerationResult {\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 [{ b64Json: item.b64_json, revisedPrompt }]\n        }\n        if (item.url) {\n          return [{ url: item.url, revisedPrompt }]\n        }\n        return []\n      },\n    )\n\n    return {\n      id: generateId(this.name),\n      model,\n      images,\n      usage: response.usage\n        ? {\n            inputTokens: response.usage.input_tokens,\n            outputTokens: response.usage.output_tokens,\n            totalTokens: response.usage.total_tokens,\n          }\n        : undefined,\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":";;;AAqCO,MAAM,yBAEH,iBAKR;AAAA,EAMA,YAAY,QAAyB,OAAe;AAClD,UAAM,OAAO,EAAE;AANjB,SAAS,OAAO;AAChB,SAAS,OAAO;AAMd,SAAK,SAAS,iBAAiB,MAAM;AAAA,EACvC;AAAA,EAEA,MAAM,eACJ,SACgC;AAChC,UAAM,EAAE,OAAO,QAAQ,gBAAgB,MAAM,WAAW;AAExD,WAAO,QAAQ,8CAA8C,KAAK,KAAK,IAAI;AAAA,MACzE,UAAU;AAAA,MACV,OAAO,KAAK;AAAA,IAAA,CACb;AAED,QAAI;AAEF,qBAAe,EAAE,QAAQ,OAAO;AAChC,wBAAkB,OAAO,IAAI;AAC7B,6BAAuB,OAAO,cAAc;AAG5C,YAAM,UAAU,KAAK,aAAa,OAAO;AAEzC,YAAM,WAAW,MAAM,KAAK,OAAO,OAAO,SAAS;AAAA,QACjD,GAAG;AAAA,QACH,QAAQ;AAAA,MAAA,CACT;AAED,aAAO,KAAK,kBAAkB,OAAO,QAAQ;AAAA,IAC/C,SAAS,OAAO;AACd,aAAO,OAAO,4BAA4B;AAAA,QACxC;AAAA,QACA,QAAQ;AAAA,MAAA,CACT;AACD,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEQ,aACN,SACuC;AACvC,UAAM,EAAE,OAAO,QAAQ,gBAAgB,MAAM,iBAAiB;AAI9D,WAAO;AAAA,MACL,GAAG;AAAA,MACH;AAAA,MACA;AAAA,MACA,GAAG,kBAAkB;AAAA,MACrB;AAAA,IAAA;AAAA,EAEJ;AAAA,EAEQ,kBACN,OACA,UACuB;AACvB,UAAM,UAAiC,SAAS,QAAQ,CAAA,GAAI;AAAA,MAC1D,CAAC,SAAgC;AAC/B,cAAM,gBAAgB,KAAK;AAC3B,YAAI,KAAK,UAAU;AACjB,iBAAO,CAAC,EAAE,SAAS,KAAK,UAAU,eAAe;AAAA,QACnD;AACA,YAAI,KAAK,KAAK;AACZ,iBAAO,CAAC,EAAE,KAAK,KAAK,KAAK,eAAe;AAAA,QAC1C;AACA,eAAO,CAAA;AAAA,MACT;AAAA,IAAA;AAGF,WAAO;AAAA,MACL,IAAI,WAAW,KAAK,IAAI;AAAA,MACxB;AAAA,MACA;AAAA,MACA,OAAO,SAAS,QACZ;AAAA,QACE,aAAa,SAAS,MAAM;AAAA,QAC5B,cAAc,SAAS,MAAM;AAAA,QAC7B,aAAa,SAAS,MAAM;AAAA,MAAA,IAE9B;AAAA,IAAA;AAAA,EAER;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;"}

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

@@ -0,0 +1,84 @@
+import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters';
+import { TranscriptionOptions, TranscriptionResult, TranscriptionWord } from '@tanstack/ai';
+import { GrokTranscriptionModel } from '../model-meta.js';
+import { GrokTranscriptionProviderOptions } from '../audio/transcription-provider-options.js';
+/**
+ * Grok-specific extension of `TranscriptionWord` that surfaces the extra
+ * fields xAI returns when diarization / confidence are enabled. The base
+ * cross-provider `TranscriptionWord` contract doesn't include these, so
+ * callers who know they're using Grok can narrow with:
+ *
+ * ```ts
+ * const words = result.words as Array<GrokTranscriptionWord> | undefined
+ * ```
+ */
+export interface GrokTranscriptionWord extends TranscriptionWord {
+    /** Model confidence for the word, when xAI returns one. */
+    confidence?: number;
+    /** Speaker index, populated when `modelOptions.diarize === true`. */
+    speaker?: number;
+}
+/**
+ * Configuration for the Grok transcription adapter.
+ *
+ * Uses direct `fetch` rather than the OpenAI SDK because xAI's `/v1/stt`
+ * endpoint is not OpenAI-compatible.
+ */
+export interface GrokTranscriptionConfig {
+    apiKey: string;
+    baseURL?: string;
+    /** Additional headers to merge into every request (e.g., test IDs). */
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * Grok Speech-to-Text Adapter.
+ *
+ * Talks to `POST {baseURL}/stt` per
+ * https://docs.x.ai/developers/rest-api-reference/inference/voice
+ */
+export declare class GrokTranscriptionAdapter<TModel extends GrokTranscriptionModel> extends BaseTranscriptionAdapter<TModel, GrokTranscriptionProviderOptions> {
+    readonly name: "grok";
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly defaultHeaders;
+    constructor(config: GrokTranscriptionConfig, model: TModel);
+    transcribe(options: TranscriptionOptions<GrokTranscriptionProviderOptions>): Promise<TranscriptionResult>;
+}
+/**
+ * Build the multipart/form-data body for `POST /v1/stt`, coercing SDK-level
+ * model options into xAI's wire format (booleans as `'true'`/`'false'`
+ * strings, numeric fields stringified, etc.).
+ *
+ * Wire-field mapping:
+ *   - `modelOptions.inverse_text_normalization` → `format` (xAI's chosen
+ *     wire-field name for the ITN boolean; the SDK surfaces it under the
+ *     clearer `inverse_text_normalization` key).
+ *   - `modelOptions.audio_format`, `sample_rate`, `multichannel`, `channels`,
+ *     `diarize` map to same-named form fields.
+ */
+export declare function buildTranscriptionFormData(options: {
+    file: File;
+    language: string | undefined;
+    modelOptions: GrokTranscriptionProviderOptions | undefined;
+}): FormData;
+/**
+ * Creates a Grok transcription adapter with an explicit API key.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGrokTranscription('grok-stt', 'xai-...')
+ * const result = await generateTranscription({
+ *   adapter,
+ *   audio: audioFile,
+ *   language: 'en',
+ * })
+ * ```
+ */
+export declare function createGrokTranscription<TModel extends GrokTranscriptionModel>(model: TModel, apiKey: string, config?: Omit<GrokTranscriptionConfig, 'apiKey'>): GrokTranscriptionAdapter<TModel>;
+/**
+ * Creates a Grok transcription adapter, reading the API key from
+ * `XAI_API_KEY` in the environment.
+ *
+ * @throws Error if `XAI_API_KEY` is not set.
+ */
+export declare function grokTranscription<TModel extends GrokTranscriptionModel>(model: TModel, config?: Omit<GrokTranscriptionConfig, 'apiKey'>): GrokTranscriptionAdapter<TModel>;

package/dist/esm/adapters/transcription.js

@@ -0,0 +1,109 @@
+import { BaseTranscriptionAdapter } from "@tanstack/ai/adapters";
+import { generateId, getGrokApiKeyFromEnv } from "../utils/client.js";
+import { toAudioFile } from "../utils/audio.js";
+const DEFAULT_GROK_BASE_URL = "https://api.x.ai/v1";
+class GrokTranscriptionAdapter extends BaseTranscriptionAdapter {
+  constructor(config, model) {
+    super(model, config);
+    this.name = "grok";
+    this.apiKey = config.apiKey;
+    this.baseURL = (config.baseURL ?? DEFAULT_GROK_BASE_URL).replace(/\/+$/, "");
+    this.defaultHeaders = config.defaultHeaders ?? {};
+  }
+  async transcribe(options) {
+    const { logger } = options;
+    const { model, audio, language, modelOptions } = options;
+    logger.request(
+      `activity=generateTranscription provider=grok model=${model}`,
+      { provider: "grok", model }
+    );
+    const file = toAudioFile(audio, modelOptions?.audio_format);
+    const form = buildTranscriptionFormData({ file, language, modelOptions });
+    try {
+      const response = await fetch(`${this.baseURL}/stt`, {
+        method: "POST",
+        headers: {
+          // `defaultHeaders` first so Authorization always wins.
+          ...this.defaultHeaders,
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: form
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(
+          `Grok transcription request failed: ${response.status} ${errorText}`
+        );
+      }
+      const data = await response.json();
+      const words = data.words?.map(
+        (w) => {
+          const tw = {
+            word: w.text,
+            start: w.start,
+            end: w.end
+          };
+          if (w.confidence !== void 0) tw.confidence = w.confidence;
+          if (w.speaker !== void 0) tw.speaker = w.speaker;
+          return tw;
+        }
+      );
+      return {
+        id: generateId(this.name),
+        model,
+        text: data.text,
+        language: data.language ?? language,
+        duration: data.duration,
+        words
+      };
+    } catch (error) {
+      logger.errors("grok.transcribe fatal", {
+        error,
+        source: "grok.transcribe"
+      });
+      throw error;
+    }
+  }
+}
+function buildTranscriptionFormData(options) {
+  const { file, language, modelOptions } = options;
+  const form = new FormData();
+  form.set("file", file);
+  if (language) form.set("language", language);
+  if (modelOptions?.audio_format !== void 0) {
+    form.set("audio_format", modelOptions.audio_format);
+  }
+  if (modelOptions?.sample_rate !== void 0) {
+    form.set("sample_rate", String(modelOptions.sample_rate));
+  }
+  if (modelOptions?.inverse_text_normalization !== void 0) {
+    form.set(
+      "format",
+      modelOptions.inverse_text_normalization ? "true" : "false"
+    );
+  }
+  if (modelOptions?.multichannel !== void 0) {
+    form.set("multichannel", modelOptions.multichannel ? "true" : "false");
+  }
+  if (modelOptions?.channels !== void 0) {
+    form.set("channels", String(modelOptions.channels));
+  }
+  if (modelOptions?.diarize !== void 0) {
+    form.set("diarize", modelOptions.diarize ? "true" : "false");
+  }
+  return form;
+}
+function createGrokTranscription(model, apiKey, config) {
+  return new GrokTranscriptionAdapter({ apiKey, ...config }, model);
+}
+function grokTranscription(model, config) {
+  const apiKey = getGrokApiKeyFromEnv();
+  return createGrokTranscription(model, apiKey, config);
+}
+export {
+  GrokTranscriptionAdapter,
+  buildTranscriptionFormData,
+  createGrokTranscription,
+  grokTranscription
+};
+//# sourceMappingURL=transcription.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transcription.js","sources":["../../../src/adapters/transcription.ts"],"sourcesContent":["import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters'\nimport { generateId, getGrokApiKeyFromEnv, toAudioFile } from '../utils'\nimport type {\n  TranscriptionOptions,\n  TranscriptionResult,\n  TranscriptionWord,\n} from '@tanstack/ai'\nimport type { GrokTranscriptionModel } from '../model-meta'\nimport type { GrokTranscriptionProviderOptions } from '../audio/transcription-provider-options'\n\n/**\n * Grok-specific extension of `TranscriptionWord` that surfaces the extra\n * fields xAI returns when diarization / confidence are enabled. The base\n * cross-provider `TranscriptionWord` contract doesn't include these, so\n * callers who know they're using Grok can narrow with:\n *\n * ```ts\n * const words = result.words as Array<GrokTranscriptionWord> | undefined\n * ```\n */\nexport interface GrokTranscriptionWord extends TranscriptionWord {\n  /** Model confidence for the word, when xAI returns one. */\n  confidence?: number\n  /** Speaker index, populated when `modelOptions.diarize === true`. */\n  speaker?: number\n}\n\nconst DEFAULT_GROK_BASE_URL = 'https://api.x.ai/v1'\n\n/**\n * Configuration for the Grok transcription adapter.\n *\n * Uses direct `fetch` rather than the OpenAI SDK because xAI's `/v1/stt`\n * endpoint is not OpenAI-compatible.\n */\nexport interface GrokTranscriptionConfig {\n  apiKey: string\n  baseURL?: string\n  /** Additional headers to merge into every request (e.g., test IDs). */\n  defaultHeaders?: Record<string, string>\n}\n\n/**\n * xAI STT response shape from `POST /v1/stt`.\n * Grok returns word-level timestamps only; no segment array.\n */\ninterface GrokSTTWord {\n  text: string\n  start: number\n  end: number\n  confidence?: number\n  speaker?: number\n}\n\ninterface GrokSTTResponse {\n  text: string\n  language?: string\n  duration?: number\n  words?: Array<GrokSTTWord>\n  channels?: Array<unknown>\n}\n\n/**\n * Grok Speech-to-Text Adapter.\n *\n * Talks to `POST {baseURL}/stt` per\n * https://docs.x.ai/developers/rest-api-reference/inference/voice\n */\nexport class GrokTranscriptionAdapter<\n  TModel extends GrokTranscriptionModel,\n> extends BaseTranscriptionAdapter<TModel, GrokTranscriptionProviderOptions> {\n  readonly name = 'grok' as const\n\n  private readonly apiKey: string\n  private readonly baseURL: string\n  private readonly defaultHeaders: Record<string, string>\n\n  constructor(config: GrokTranscriptionConfig, model: TModel) {\n    super(model, config)\n    this.apiKey = config.apiKey\n    this.baseURL = (config.baseURL ?? DEFAULT_GROK_BASE_URL).replace(/\\/+$/, '')\n    this.defaultHeaders = config.defaultHeaders ?? {}\n  }\n\n  async transcribe(\n    options: TranscriptionOptions<GrokTranscriptionProviderOptions>,\n  ): Promise<TranscriptionResult> {\n    const { logger } = options\n    const { model, audio, language, modelOptions } = options\n\n    logger.request(\n      `activity=generateTranscription provider=grok model=${model}`,\n      { provider: 'grok', model },\n    )\n\n    const file = toAudioFile(audio, modelOptions?.audio_format)\n    const form = buildTranscriptionFormData({ file, language, modelOptions })\n\n    try {\n      const response = await fetch(`${this.baseURL}/stt`, {\n        method: 'POST',\n        headers: {\n          // `defaultHeaders` first so Authorization always wins.\n          ...this.defaultHeaders,\n          Authorization: `Bearer ${this.apiKey}`,\n        },\n        body: form,\n      })\n\n      if (!response.ok) {\n        const errorText = await response.text()\n        throw new Error(\n          `Grok transcription request failed: ${response.status} ${errorText}`,\n        )\n      }\n\n      const data = (await response.json()) as GrokSTTResponse\n\n      const words: Array<TranscriptionWord> | undefined = data.words?.map(\n        (w) => {\n          // Construct a GrokTranscriptionWord so that `confidence` and\n          // `speaker` (when xAI returns them under `diarize` / confidence\n          // mode) are preserved on the result. The returned array is typed\n          // as `Array<TranscriptionWord>` per the cross-provider contract;\n          // callers who want the extras narrow via `as Array<GrokTranscriptionWord>`.\n          const tw: GrokTranscriptionWord = {\n            word: w.text,\n            start: w.start,\n            end: w.end,\n          }\n          if (w.confidence !== undefined) tw.confidence = w.confidence\n          if (w.speaker !== undefined) tw.speaker = w.speaker\n          return tw\n        },\n      )\n\n      return {\n        id: generateId(this.name),\n        model,\n        text: data.text,\n        language: data.language ?? language,\n        duration: data.duration,\n        words,\n      }\n    } catch (error) {\n      logger.errors('grok.transcribe fatal', {\n        error,\n        source: 'grok.transcribe',\n      })\n      throw error\n    }\n  }\n}\n\n/**\n * Build the multipart/form-data body for `POST /v1/stt`, coercing SDK-level\n * model options into xAI's wire format (booleans as `'true'`/`'false'`\n * strings, numeric fields stringified, etc.).\n *\n * Wire-field mapping:\n *   - `modelOptions.inverse_text_normalization` → `format` (xAI's chosen\n *     wire-field name for the ITN boolean; the SDK surfaces it under the\n *     clearer `inverse_text_normalization` key).\n *   - `modelOptions.audio_format`, `sample_rate`, `multichannel`, `channels`,\n *     `diarize` map to same-named form fields.\n */\nexport function buildTranscriptionFormData(options: {\n  file: File\n  language: string | undefined\n  modelOptions: GrokTranscriptionProviderOptions | undefined\n}): FormData {\n  const { file, language, modelOptions } = options\n  const form = new FormData()\n  form.set('file', file)\n  if (language) form.set('language', language)\n  if (modelOptions?.audio_format !== undefined) {\n    form.set('audio_format', modelOptions.audio_format)\n  }\n  if (modelOptions?.sample_rate !== undefined) {\n    form.set('sample_rate', String(modelOptions.sample_rate))\n  }\n  if (modelOptions?.inverse_text_normalization !== undefined) {\n    form.set(\n      'format',\n      modelOptions.inverse_text_normalization ? 'true' : 'false',\n    )\n  }\n  if (modelOptions?.multichannel !== undefined) {\n    form.set('multichannel', modelOptions.multichannel ? 'true' : 'false')\n  }\n  if (modelOptions?.channels !== undefined) {\n    form.set('channels', String(modelOptions.channels))\n  }\n  if (modelOptions?.diarize !== undefined) {\n    form.set('diarize', modelOptions.diarize ? 'true' : 'false')\n  }\n  return form\n}\n\n/**\n * Creates a Grok transcription adapter with an explicit API key.\n *\n * @example\n * ```typescript\n * const adapter = createGrokTranscription('grok-stt', 'xai-...')\n * const result = await generateTranscription({\n *   adapter,\n *   audio: audioFile,\n *   language: 'en',\n * })\n * ```\n */\nexport function createGrokTranscription<TModel extends GrokTranscriptionModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokTranscriptionConfig, 'apiKey'>,\n): GrokTranscriptionAdapter<TModel> {\n  return new GrokTranscriptionAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Grok transcription adapter, reading the API key from\n * `XAI_API_KEY` in the environment.\n *\n * @throws Error if `XAI_API_KEY` is not set.\n */\nexport function grokTranscription<TModel extends GrokTranscriptionModel>(\n  model: TModel,\n  config?: Omit<GrokTranscriptionConfig, 'apiKey'>,\n): GrokTranscriptionAdapter<TModel> {\n  const apiKey = getGrokApiKeyFromEnv()\n  return createGrokTranscription(model, apiKey, config)\n}\n"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,70 @@
+import { BaseTTSAdapter } from '@tanstack/ai/adapters';
+import { TTSOptions, TTSResult } from '@tanstack/ai';
+import { GrokTTSModel } from '../model-meta.js';
+import { GrokTTSCodec, GrokTTSProviderOptions } from '../audio/tts-provider-options.js';
+/**
+ * Configuration for the Grok TTS adapter.
+ *
+ * Unlike chat/image/summarize adapters, TTS does not use the OpenAI SDK
+ * because xAI's `/v1/tts` endpoint is not OpenAI-compatible. This config
+ * is a minimal subset suitable for direct `fetch` calls.
+ */
+export interface GrokSpeechConfig {
+    apiKey: string;
+    baseURL?: string;
+    /** Additional headers to merge into every request (e.g., test IDs). */
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * Grok Text-to-Speech Adapter.
+ *
+ * Talks to `POST {baseURL}/tts` per
+ * https://docs.x.ai/developers/model-capabilities/audio/text-to-speech
+ */
+export declare class GrokSpeechAdapter<TModel extends GrokTTSModel> extends BaseTTSAdapter<TModel, GrokTTSProviderOptions> {
+    readonly name: "grok";
+    private readonly apiKey;
+    private readonly baseURL;
+    private readonly defaultHeaders;
+    constructor(config: GrokSpeechConfig, model: TModel);
+    generateSpeech(options: TTSOptions<GrokTTSProviderOptions>): Promise<TTSResult>;
+}
+/**
+ * Build the JSON body for `POST /v1/tts`, resolving codec / sample-rate / voice
+ * defaults in one place.
+ *
+ * Returns the request `body`, the resolved `codec`, and the `sampleRateForContentType`
+ * used by the caller to label the response via `getContentType`.
+ */
+export declare function buildTTSRequestBody(options: {
+    text: string;
+    voice: string | undefined;
+    format: TTSOptions['format'] | undefined;
+    modelOptions: GrokTTSProviderOptions | undefined;
+}): {
+    body: Record<string, unknown>;
+    codec: GrokTTSCodec;
+    sampleRateForContentType: number;
+};
+export declare function getContentType(codec: GrokTTSCodec, sampleRate: number): string;
+/**
+ * Creates a Grok speech (TTS) adapter with an explicit API key.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGrokSpeech('grok-tts', 'xai-...')
+ * const result = await generateSpeech({
+ *   adapter,
+ *   text: 'Hello from Grok',
+ *   voice: 'eve',
+ * })
+ * ```
+ */
+export declare function createGrokSpeech<TModel extends GrokTTSModel>(model: TModel, apiKey: string, config?: Omit<GrokSpeechConfig, 'apiKey'>): GrokSpeechAdapter<TModel>;
+/**
+ * Creates a Grok speech (TTS) adapter, reading the API key from
+ * `XAI_API_KEY` in the environment.
+ *
+ * @throws Error if `XAI_API_KEY` is not set.
+ */
+export declare function grokSpeech<TModel extends GrokTTSModel>(model: TModel, config?: Omit<GrokSpeechConfig, 'apiKey'>): GrokSpeechAdapter<TModel>;

package/dist/esm/adapters/tts.js

@@ -0,0 +1,137 @@
+import { BaseTTSAdapter } from "@tanstack/ai/adapters";
+import { generateId, getGrokApiKeyFromEnv } from "../utils/client.js";
+import { arrayBufferToBase64 } from "../utils/audio.js";
+const DEFAULT_GROK_BASE_URL = "https://api.x.ai/v1";
+class GrokSpeechAdapter extends BaseTTSAdapter {
+  constructor(config, model) {
+    super(model, config);
+    this.name = "grok";
+    this.apiKey = config.apiKey;
+    this.baseURL = (config.baseURL ?? DEFAULT_GROK_BASE_URL).replace(/\/+$/, "");
+    this.defaultHeaders = config.defaultHeaders ?? {};
+  }
+  async generateSpeech(options) {
+    const { logger } = options;
+    const { model, text, voice, format, modelOptions } = options;
+    logger.request(`activity=generateSpeech provider=grok model=${model}`, {
+      provider: "grok",
+      model
+    });
+    const { body, codec, sampleRateForContentType } = buildTTSRequestBody({
+      text,
+      voice,
+      format,
+      modelOptions
+    });
+    try {
+      const response = await fetch(`${this.baseURL}/tts`, {
+        method: "POST",
+        headers: {
+          // `defaultHeaders` first so the adapter's Authorization / Content-Type
+          // always win — otherwise a caller-supplied `Authorization` header
+          // could silently clobber the bearer token.
+          ...this.defaultHeaders,
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(
+          `Grok TTS request failed: ${response.status} ${errorText}`
+        );
+      }
+      const arrayBuffer = await response.arrayBuffer();
+      const audio = arrayBufferToBase64(arrayBuffer);
+      return {
+        id: generateId(this.name),
+        model,
+        audio,
+        format: codec,
+        contentType: getContentType(codec, sampleRateForContentType)
+      };
+    } catch (error) {
+      logger.errors("grok.generateSpeech fatal", {
+        error,
+        source: "grok.generateSpeech"
+      });
+      throw error;
+    }
+  }
+}
+function buildTTSRequestBody(options) {
+  const { text, voice, format, modelOptions } = options;
+  const codec = pickCodec(modelOptions?.codec, format);
+  const callerSampleRate = modelOptions?.sample_rate;
+  const pcmDefault = 24e3;
+  const needsRateInContentType = codec === "pcm";
+  const outputFormat = { codec };
+  if (callerSampleRate !== void 0) {
+    outputFormat.sample_rate = callerSampleRate;
+  } else if (needsRateInContentType) {
+    outputFormat.sample_rate = pcmDefault;
+  }
+  if (codec === "mp3" && modelOptions?.bit_rate !== void 0) {
+    outputFormat.bit_rate = modelOptions.bit_rate;
+  }
+  const sampleRateForContentType = callerSampleRate ?? pcmDefault;
+  const body = {
+    text,
+    voice_id: voice ?? "eve",
+    language: modelOptions?.language ?? "en",
+    output_format: outputFormat
+  };
+  if (modelOptions?.optimize_streaming_latency !== void 0) {
+    body.optimize_streaming_latency = modelOptions.optimize_streaming_latency;
+  }
+  if (modelOptions?.text_normalization !== void 0) {
+    body.text_normalization = modelOptions.text_normalization;
+  }
+  return { body, codec, sampleRateForContentType };
+}
+function pickCodec(codecOverride, format) {
+  if (codecOverride) return codecOverride;
+  if (!format) return "mp3";
+  switch (format) {
+    case "mp3":
+    case "wav":
+    case "pcm":
+      return format;
+    case "flac":
+    case "opus":
+    case "aac":
+      return "mp3";
+    default:
+      return "mp3";
+  }
+}
+function getContentType(codec, sampleRate) {
+  switch (codec) {
+    case "mp3":
+      return "audio/mpeg";
+    case "wav":
+      return "audio/wav";
+    case "pcm":
+      return `audio/L16;rate=${sampleRate}`;
+    case "mulaw":
+      return sampleRate === 8e3 ? "audio/basic" : `audio/PCMU;rate=${sampleRate}`;
+    case "alaw":
+      return sampleRate === 8e3 ? "audio/x-alaw-basic" : `audio/PCMA;rate=${sampleRate}`;
+  }
+}
+function createGrokSpeech(model, apiKey, config) {
+  return new GrokSpeechAdapter({ apiKey, ...config }, model);
+}
+function grokSpeech(model, config) {
+  const apiKey = getGrokApiKeyFromEnv();
+  return createGrokSpeech(model, apiKey, config);
+}
+export {
+  GrokSpeechAdapter,
+  buildTTSRequestBody,
+  createGrokSpeech,
+  getContentType,
+  grokSpeech
+};
+//# sourceMappingURL=tts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tts.js","sources":["../../../src/adapters/tts.ts"],"sourcesContent":["import { BaseTTSAdapter } from '@tanstack/ai/adapters'\nimport { arrayBufferToBase64, generateId, getGrokApiKeyFromEnv } from '../utils'\nimport type { TTSOptions, TTSResult } from '@tanstack/ai'\nimport type { GrokTTSModel } from '../model-meta'\nimport type {\n  GrokTTSCodec,\n  GrokTTSProviderOptions,\n  GrokTTSVoice,\n} from '../audio/tts-provider-options'\n\nconst DEFAULT_GROK_BASE_URL = 'https://api.x.ai/v1'\n\n/**\n * Configuration for the Grok TTS adapter.\n *\n * Unlike chat/image/summarize adapters, TTS does not use the OpenAI SDK\n * because xAI's `/v1/tts` endpoint is not OpenAI-compatible. This config\n * is a minimal subset suitable for direct `fetch` calls.\n */\nexport interface GrokSpeechConfig {\n  apiKey: string\n  baseURL?: string\n  /** Additional headers to merge into every request (e.g., test IDs). */\n  defaultHeaders?: Record<string, string>\n}\n\n/**\n * Grok Text-to-Speech Adapter.\n *\n * Talks to `POST {baseURL}/tts` per\n * https://docs.x.ai/developers/model-capabilities/audio/text-to-speech\n */\nexport class GrokSpeechAdapter<\n  TModel extends GrokTTSModel,\n> extends BaseTTSAdapter<TModel, GrokTTSProviderOptions> {\n  readonly name = 'grok' as const\n\n  private readonly apiKey: string\n  private readonly baseURL: string\n  private readonly defaultHeaders: Record<string, string>\n\n  constructor(config: GrokSpeechConfig, model: TModel) {\n    super(model, config)\n    this.apiKey = config.apiKey\n    this.baseURL = (config.baseURL ?? DEFAULT_GROK_BASE_URL).replace(/\\/+$/, '')\n    this.defaultHeaders = config.defaultHeaders ?? {}\n  }\n\n  async generateSpeech(\n    options: TTSOptions<GrokTTSProviderOptions>,\n  ): Promise<TTSResult> {\n    const { logger } = options\n    const { model, text, voice, format, modelOptions } = options\n\n    logger.request(`activity=generateSpeech provider=grok model=${model}`, {\n      provider: 'grok',\n      model,\n    })\n\n    const { body, codec, sampleRateForContentType } = buildTTSRequestBody({\n      text,\n      voice,\n      format,\n      modelOptions,\n    })\n\n    try {\n      const response = await fetch(`${this.baseURL}/tts`, {\n        method: 'POST',\n        headers: {\n          // `defaultHeaders` first so the adapter's Authorization / Content-Type\n          // always win — otherwise a caller-supplied `Authorization` header\n          // could silently clobber the bearer token.\n          ...this.defaultHeaders,\n          Authorization: `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify(body),\n      })\n\n      if (!response.ok) {\n        const errorText = await response.text()\n        throw new Error(\n          `Grok TTS request failed: ${response.status} ${errorText}`,\n        )\n      }\n\n      const arrayBuffer = await response.arrayBuffer()\n      const audio = arrayBufferToBase64(arrayBuffer)\n\n      return {\n        id: generateId(this.name),\n        model,\n        audio,\n        format: codec,\n        contentType: getContentType(codec, sampleRateForContentType),\n      }\n    } catch (error) {\n      logger.errors('grok.generateSpeech fatal', {\n        error,\n        source: 'grok.generateSpeech',\n      })\n      throw error\n    }\n  }\n}\n\n/**\n * Build the JSON body for `POST /v1/tts`, resolving codec / sample-rate / voice\n * defaults in one place.\n *\n * Returns the request `body`, the resolved `codec`, and the `sampleRateForContentType`\n * used by the caller to label the response via `getContentType`.\n */\nexport function buildTTSRequestBody(options: {\n  text: string\n  voice: string | undefined\n  format: TTSOptions['format'] | undefined\n  modelOptions: GrokTTSProviderOptions | undefined\n}): {\n  body: Record<string, unknown>\n  codec: GrokTTSCodec\n  sampleRateForContentType: number\n} {\n  const { text, voice, format, modelOptions } = options\n\n  const codec = pickCodec(modelOptions?.codec, format)\n\n  // Only forward `sample_rate` when either:\n  //   - the caller explicitly set `modelOptions.sample_rate`, or\n  //   - the codec's Content-Type carries the rate (pcm → audio/L16;rate=…).\n  // For mp3/wav/opus/aac/flac we leave sample_rate unset so xAI's server\n  // default applies.\n  const callerSampleRate = modelOptions?.sample_rate\n  // Default sample rate documented in GrokTTSProviderOptions is 24000 Hz —\n  // used only when we MUST attach a rate to the contentType (pcm) and the\n  // caller didn't pick one.\n  const pcmDefault = 24000\n  const needsRateInContentType = codec === 'pcm'\n\n  const outputFormat: Record<string, unknown> = { codec }\n  if (callerSampleRate !== undefined) {\n    outputFormat.sample_rate = callerSampleRate\n  } else if (needsRateInContentType) {\n    outputFormat.sample_rate = pcmDefault\n  }\n  if (codec === 'mp3' && modelOptions?.bit_rate !== undefined) {\n    outputFormat.bit_rate = modelOptions.bit_rate\n  }\n\n  // pcm embeds the rate in `audio/L16;rate=…`; mulaw/alaw embed it in\n  // `audio/PCMU;rate=…` / `audio/PCMA;rate=…` when non-default. mp3/wav\n  // don't carry a rate parameter so the value is unused for those.\n  const sampleRateForContentType = callerSampleRate ?? pcmDefault\n\n  const body: Record<string, unknown> = {\n    text,\n    voice_id: (voice as GrokTTSVoice | undefined) ?? 'eve',\n    language: modelOptions?.language ?? 'en',\n    output_format: outputFormat,\n  }\n  if (modelOptions?.optimize_streaming_latency !== undefined) {\n    body.optimize_streaming_latency = modelOptions.optimize_streaming_latency\n  }\n  if (modelOptions?.text_normalization !== undefined) {\n    body.text_normalization = modelOptions.text_normalization\n  }\n\n  return { body, codec, sampleRateForContentType }\n}\n\n/**\n * Maps the cross-provider `TTSOptions.format` onto Grok's supported codecs.\n * `opus`, `aac`, and `flac` are not supported by xAI TTS (which only exposes\n * mp3/wav/pcm/mulaw/alaw) — we fall back to mp3. An explicit\n * `modelOptions.codec` always wins.\n */\nfunction pickCodec(\n  codecOverride: GrokTTSCodec | undefined,\n  format: TTSOptions['format'] | undefined,\n): GrokTTSCodec {\n  if (codecOverride) return codecOverride\n  if (!format) return 'mp3'\n  switch (format) {\n    case 'mp3':\n    case 'wav':\n    case 'pcm':\n      return format\n    case 'flac':\n    case 'opus':\n    case 'aac':\n      return 'mp3'\n    default:\n      return 'mp3'\n  }\n}\n\nexport function getContentType(\n  codec: GrokTTSCodec,\n  sampleRate: number,\n): string {\n  switch (codec) {\n    case 'mp3':\n      return 'audio/mpeg'\n    case 'wav':\n      return 'audio/wav'\n    case 'pcm':\n      // `audio/L16` requires a `rate` parameter per RFC 3551/3555.\n      return `audio/L16;rate=${sampleRate}`\n    case 'mulaw':\n      // `audio/basic` is 8 kHz mono by RFC 2046 registration. For non-8kHz\n      // streams xAI still produces mulaw-encoded bytes at the requested\n      // rate, but the registered MIME can't carry that rate — so we use\n      // the non-standard but commonly-supported `audio/PCMU;rate=…` (RFC 3551\n      // RTP payload name) whenever the caller asked for a rate other than\n      // 8000, and keep `audio/basic` for the standard 8kHz case.\n      return sampleRate === 8000\n        ? 'audio/basic'\n        : `audio/PCMU;rate=${sampleRate}`\n    case 'alaw':\n      return sampleRate === 8000\n        ? 'audio/x-alaw-basic'\n        : `audio/PCMA;rate=${sampleRate}`\n  }\n}\n\n/**\n * Creates a Grok speech (TTS) adapter with an explicit API key.\n *\n * @example\n * ```typescript\n * const adapter = createGrokSpeech('grok-tts', 'xai-...')\n * const result = await generateSpeech({\n *   adapter,\n *   text: 'Hello from Grok',\n *   voice: 'eve',\n * })\n * ```\n */\nexport function createGrokSpeech<TModel extends GrokTTSModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokSpeechConfig, 'apiKey'>,\n): GrokSpeechAdapter<TModel> {\n  return new GrokSpeechAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Grok speech (TTS) adapter, reading the API key from\n * `XAI_API_KEY` in the environment.\n *\n * @throws Error if `XAI_API_KEY` is not set.\n */\nexport function grokSpeech<TModel extends GrokTTSModel>(\n  model: TModel,\n  config?: Omit<GrokSpeechConfig, 'apiKey'>,\n): GrokSpeechAdapter<TModel> {\n  const apiKey = getGrokApiKeyFromEnv()\n  return createGrokSpeech(model, apiKey, config)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/audio/transcription-provider-options.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Grok STT supported audio formats.
+ * See https://docs.x.ai/developers/rest-api-reference/inference/voice
+ */
+export type GrokSTTAudioFormat = 'pcm' | 'mulaw' | 'alaw' | 'wav' | 'mp3' | 'ogg' | 'opus' | 'flac' | 'aac' | 'mp4' | 'm4a' | 'mkv';
+/**
+ * Provider-specific options for Grok transcription (`POST /v1/stt`).
+ */
+export interface GrokTranscriptionProviderOptions {
+    /**
+     * The format of the provided audio. Required for raw codecs (pcm, mulaw, alaw).
+     */
+    audio_format?: GrokSTTAudioFormat;
+    /**
+     * Sample rate of the audio (Hz). Required for raw codecs.
+     */
+    sample_rate?: number;
+    /**
+     * Apply inverse text normalization (e.g. "one hundred" → "100"). Requires
+     * `language` to be set on the core `TranscriptionOptions`.
+     *
+     * NOTE: xAI's STT API exposes this on the wire as `format` (a boolean
+     * toggle). We surface it under the clearer name
+     * `inverse_text_normalization` on the SDK, and translate to the wire name
+     * inside the adapter.
+     */
+    inverse_text_normalization?: boolean;
+    /**
+     * Treat the audio as multichannel. When enabled, `channels` must also be set.
+     */
+    multichannel?: boolean;
+    /**
+     * Channel count for multichannel raw audio (2–8).
+     */
+    channels?: number;
+    /**
+     * Enable speaker diarization. When true, response words include a `speaker`
+     * field.
+     */
+    diarize?: boolean;
+}

package/dist/esm/audio/tts-provider-options.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Grok TTS voice options.
+ * See https://docs.x.ai/developers/model-capabilities/audio/text-to-speech
+ */
+export type GrokTTSVoice = 'eve' | 'ara' | 'rex' | 'sal' | 'leo';
+/**
+ * Grok TTS output audio codecs.
+ * Grok does NOT support opus or aac; those formats are mapped to mp3.
+ */
+export type GrokTTSCodec = 'mp3' | 'wav' | 'pcm' | 'mulaw' | 'alaw';
+/**
+ * Provider-specific options for Grok TTS (`POST /v1/tts`).
+ */
+export interface GrokTTSProviderOptions {
+    /**
+     * BCP-47 language code (e.g., `en`, `zh`, `pt-BR`) or `'auto'` for detection.
+     * Defaults to `'en'` when not provided.
+     */
+    language?: string;
+    /**
+     * Audio codec. Overrides the `format` field on `TTSOptions` when set.
+     */
+    codec?: GrokTTSCodec;
+    /**
+     * Sample rate in Hz. Valid values: 8000, 16000, 22050, 24000, 44100, 48000.
+     * Defaults to 24000.
+     */
+    sample_rate?: 8000 | 16000 | 22050 | 24000 | 44100 | 48000;
+    /**
+     * Bit rate for MP3 output. Ignored for other codecs.
+     * Valid values: 32000, 64000, 96000, 128000, 192000. Defaults to 128000.
+     */
+    bit_rate?: 32000 | 64000 | 96000 | 128000 | 192000;
+    /**
+     * Set to 1 for lower latency streaming; 0 (default) for normal quality.
+     */
+    optimize_streaming_latency?: 0 | 1;
+    /**
+     * Enable text normalization. Defaults to false.
+     */
+    text_normalization?: boolean;
+}

package/dist/esm/index.d.ts

@@ -2,6 +2,12 @@ export { GrokTextAdapter, createGrokText, grokText, type GrokTextConfig, type Gr
 export { GrokSummarizeAdapter, createGrokSummarize, grokSummarize, type GrokSummarizeConfig, type GrokSummarizeProviderOptions, type GrokSummarizeModel, } from './adapters/summarize.js';
 export { GrokImageAdapter, createGrokImage, grokImage, type GrokImageConfig, } from './adapters/image.js';
 export type { GrokImageProviderOptions, GrokImageModelProviderOptionsByName, } from './image/image-provider-options.js';
-export type { GrokChatModelProviderOptionsByName, GrokChatModelToolCapabilitiesByName, GrokModelInputModalitiesByName, ResolveProviderOptions, ResolveInputModalities, GrokChatModel, GrokImageModel, } from './model-meta.js';
-export { GROK_CHAT_MODELS, GROK_IMAGE_MODELS } from './model-meta.js';
+export { GrokSpeechAdapter, createGrokSpeech, grokSpeech, type GrokSpeechConfig, } from './adapters/tts.js';
+export type { GrokTTSProviderOptions, GrokTTSVoice, GrokTTSCodec, } from './audio/tts-provider-options.js';
+export { GrokTranscriptionAdapter, createGrokTranscription, grokTranscription, type GrokTranscriptionConfig, } from './adapters/transcription.js';
+export type { GrokTranscriptionProviderOptions, GrokSTTAudioFormat, } from './audio/transcription-provider-options.js';
+export type { GrokChatModelProviderOptionsByName, GrokChatModelToolCapabilitiesByName, GrokModelInputModalitiesByName, ResolveProviderOptions, ResolveInputModalities, GrokChatModel, GrokImageModel, GrokTTSModel, GrokTranscriptionModel, GrokRealtimeModel, } from './model-meta.js';
+export { GROK_CHAT_MODELS, GROK_IMAGE_MODELS, GROK_TTS_MODELS, GROK_TRANSCRIPTION_MODELS, GROK_REALTIME_MODELS, } from './model-meta.js';
 export type { GrokTextMetadata, GrokImageMetadata, GrokAudioMetadata, GrokVideoMetadata, GrokDocumentMetadata, GrokMessageMetadataByModality, } from './message-types.js';
+export { grokRealtimeToken, grokRealtime } from './realtime/index.js';
+export type { GrokRealtimeVoice, GrokRealtimeTokenOptions, GrokRealtimeOptions, GrokTurnDetection, GrokSemanticVADConfig, GrokServerVADConfig, } from './realtime/index.js';