@tanstack/ai-grok 0.13.0 → 0.14.1

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

@@ -0,0 +1,128 @@
+import { BaseVideoAdapter, DurationOptions } from '@tanstack/ai/adapters';
+import { VideoGenerationOptions, VideoJobResult, VideoStatusResult, VideoUrlResult } from '@tanstack/ai';
+import { GrokVideoModel } from '../model-meta.js';
+import { GrokVideoModelDurationByName, GrokVideoModelInputModalitiesByName, GrokVideoModelProviderOptionsByName, GrokVideoModelSizeByName, GrokVideoProviderOptions } from '../video/video-provider-options.js';
+import { GrokClientConfig } from '../utils.js';
+/**
+ * Configuration for Grok video adapter.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface GrokVideoConfig extends GrokClientConfig {
+}
+/**
+ * Grok Video Generation Adapter (xAI Imagine API)
+ *
+ * Tree-shakeable adapter for the grok-imagine video models using the
+ * async jobs/polling architecture: create a generation request, poll it,
+ * then read the completed video URL.
+ *
+ * `grok-imagine-video` (v1.0) supports text-to-video and image-to-video.
+ * `grok-imagine-video-1.5` is image-to-video only — every request needs an
+ * image prompt part as the starting frame, and the adapter rejects a
+ * text-only prompt with a clear error rather than a raw API 400.
+ *
+ * The Imagine video endpoints are not part of the OpenAI SDK surface (and
+ * xAI rejects the SDK's multipart paths), so requests are plain JSON calls
+ * issued with the configured `fetch` (or the global one).
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * Features:
+ * - Async job-based video generation (1–15 second clips with audio)
+ * - Aspect-ratio sizing via the "aspectRatio_resolution" size template
+ *   (e.g. '16:9_720p'), consistent with the grok-imagine image models
+ * - Image-to-video via an `image` prompt part (starting frame URL or data URI)
+ * - Usage reporting: billed seconds (`unitsBilled`) and exact cost
+ */
+export declare class GrokVideoAdapter<TModel extends GrokVideoModel> extends BaseVideoAdapter<TModel, GrokVideoProviderOptions, GrokVideoModelProviderOptionsByName, GrokVideoModelSizeByName, GrokVideoModelInputModalitiesByName, GrokVideoModelDurationByName> {
+    readonly name: "grok";
+    private readonly clientConfig;
+    constructor(config: GrokVideoConfig, model: TModel);
+    private get fetch();
+    private request;
+    /**
+     * Reads the error message out of an Imagine API error body
+     * (`{"code": "...", "error": "..."}`), falling back to the raw text.
+     */
+    private errorMessage;
+    createVideoJob(options: VideoGenerationOptions<GrokVideoProviderOptions, GrokVideoModelSizeByName[TModel], GrokVideoModelDurationByName[TModel]>): Promise<VideoJobResult>;
+    private retrieveJob;
+    getVideoStatus(jobId: string): Promise<VideoStatusResult>;
+    getVideoUrl(jobId: string): Promise<VideoUrlResult>;
+    /**
+     * Maps Imagine API job statuses onto the generic video status set. The
+     * API reports 'pending' while queued/generating (with a numeric
+     * `progress`), then a terminal 'done' / 'failed' / 'expired'.
+     */
+    protected mapStatus(apiStatus: string | undefined): 'pending' | 'processing' | 'completed' | 'failed';
+    /**
+     * Both grok-imagine video models accept a continuous 1–15 integer-second
+     * range. Consumers can use this to render UI without provider knowledge.
+     */
+    availableDurations(): DurationOptions<GrokVideoModelDurationByName[TModel]>;
+    /**
+     * Coerce a raw seconds value to the closest valid duration (clamped to
+     * [1, 15] and rounded to whole seconds).
+     */
+    snapDuration(seconds: number): GrokVideoModelDurationByName[TModel] | undefined;
+}
+/**
+ * Creates a Grok video adapter with an explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * @param model - The model name (e.g., 'grok-imagine-video')
+ * @param apiKey - Your xAI API key
+ * @param config - Optional additional configuration
+ * @returns Configured Grok video adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * // grok-imagine-video (v1.0) supports text-to-video.
+ * const adapter = createGrokVideo('grok-imagine-video', 'xai-...');
+ *
+ * const { jobId } = await generateVideo({
+ *   adapter,
+ *   prompt: 'A beautiful sunset over the ocean',
+ *   size: '16:9_720p',
+ *   duration: 5
+ * });
+ * ```
+ */
+export declare function createGrokVideo<TModel extends GrokVideoModel>(model: TModel, apiKey: string, config?: Omit<GrokVideoConfig, 'apiKey'>): GrokVideoAdapter<TModel>;
+/**
+ * Creates a Grok video adapter with automatic API key detection from environment variables.
+ * Type resolution happens here at the call site.
+ *
+ * Looks for `XAI_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * @param model - The model name (e.g., 'grok-imagine-video-1.5')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured Grok video adapter instance with resolved types
+ * @throws Error if XAI_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * // Automatically uses XAI_API_KEY from environment
+ * const adapter = grokVideo('grok-imagine-video-1.5');
+ *
+ * // Image-to-video only: the prompt must carry a starting-frame image part.
+ * const { jobId } = await generateVideo({
+ *   adapter,
+ *   prompt: [
+ *     { type: 'text', content: 'Make the cat start playing the piano' },
+ *     { type: 'image', source: { type: 'url', value: 'https://example.com/cat.png' } },
+ *   ],
+ * });
+ *
+ * // Poll for status
+ * const status = await getVideoJobStatus({ adapter, jobId });
+ * ```
+ */
+export declare function grokVideo<TModel extends GrokVideoModel>(model: TModel, config?: Omit<GrokVideoConfig, 'apiKey'>): GrokVideoAdapter<TModel>;

package/dist/esm/adapters/video.js

@@ -0,0 +1,237 @@
+import { resolveMediaPrompt } from "@tanstack/ai";
+import { BaseVideoAdapter, snapToDurationOption } from "@tanstack/ai/adapters";
+import { toRunErrorPayload } from "@tanstack/ai/adapter-internals";
+import { withGrokDefaults, getGrokApiKeyFromEnv } from "../utils/client.js";
+import { validateVideoSize, isImageToVideoOnlyModel, parseGrokVideoSize, getGrokVideoDurationOptions } from "../video/video-provider-options.js";
+const USD_TICKS_PER_DOLLAR = 1e10;
+function imagePartToUrl(part) {
+  if (part.source.type === "url") return part.source.value;
+  return `data:${part.source.mimeType};base64,${part.source.value}`;
+}
+function buildGrokVideoUsage(response) {
+  const seconds = response.video?.duration;
+  const ticks = response.usage?.cost_in_usd_ticks;
+  if (seconds === void 0 && ticks === void 0) return void 0;
+  return {
+    promptTokens: 0,
+    completionTokens: 0,
+    totalTokens: 0,
+    ...seconds !== void 0 && { unitsBilled: seconds },
+    ...ticks !== void 0 && { cost: ticks / USD_TICKS_PER_DOLLAR }
+  };
+}
+class GrokVideoAdapter extends BaseVideoAdapter {
+  name = "grok";
+  clientConfig;
+  constructor(config, model) {
+    super({}, model);
+    this.clientConfig = withGrokDefaults(config);
+  }
+  get fetch() {
+    return this.clientConfig.fetch ?? fetch;
+  }
+  async request(path, init) {
+    return await this.fetch(`${this.clientConfig.baseURL}${path}`, {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.clientConfig.apiKey}`
+      }
+    });
+  }
+  /**
+   * Reads the error message out of an Imagine API error body
+   * (`{"code": "...", "error": "..."}`), falling back to the raw text.
+   */
+  async errorMessage(response) {
+    const body = await response.text();
+    try {
+      const parsed = JSON.parse(body);
+      if (typeof parsed === "object" && parsed !== null && "error" in parsed && typeof parsed.error === "string") {
+        return parsed.error;
+      }
+    } catch {
+    }
+    return body;
+  }
+  async createVideoJob(options) {
+    const { model, size, modelOptions, logger } = options;
+    validateVideoSize(model, size);
+    const rawDuration = modelOptions?.duration ?? options.duration;
+    const duration = rawDuration !== void 0 ? this.snapDuration(rawDuration) : void 0;
+    const resolved = resolveMediaPrompt(options.prompt);
+    if (resolved.videos.length > 0) {
+      throw new Error(
+        `${this.name}.createVideoJob does not support video prompt parts (model: ${model}).`
+      );
+    }
+    if (resolved.audios.length > 0) {
+      throw new Error(
+        `${this.name}.createVideoJob does not support audio prompt parts (model: ${model}).`
+      );
+    }
+    if (resolved.images.length === 0 && isImageToVideoOnlyModel(model)) {
+      throw new Error(
+        `${this.name}: ${model} does not support text-to-video — it is image-to-video only. Include an image prompt part as the starting frame, or use 'grok-imagine-video' for text-to-video.`
+      );
+    }
+    if (resolved.images.length > 1) {
+      throw new Error(
+        `${this.name}: ${model} accepts at most one starting-frame image; received ${resolved.images.length}.`
+      );
+    }
+    const [startFrame] = resolved.images;
+    const parsedSize = size !== void 0 ? parseGrokVideoSize(size) : void 0;
+    const request = {
+      model,
+      prompt: resolved.text,
+      ...startFrame && { image: { url: imagePartToUrl(startFrame) } },
+      ...parsedSize && {
+        aspect_ratio: parsedSize.aspectRatio,
+        ...parsedSize.resolution !== void 0 && {
+          resolution: parsedSize.resolution
+        }
+      },
+      ...modelOptions,
+      // Spread after modelOptions so the snapped duration is authoritative
+      // (modelOptions.duration is folded into `duration` via snapDuration above).
+      ...duration !== void 0 && { duration }
+    };
+    try {
+      logger.request(
+        `activity=video.create provider=${this.name} model=${model} size=${size ?? "default"} duration=${duration ?? "default"}`,
+        { provider: this.name, model }
+      );
+      const response = await this.request("/videos/generations", {
+        method: "POST",
+        body: JSON.stringify(request)
+      });
+      if (!response.ok) {
+        throw new Error(
+          `grok: video generation request failed (${response.status} ${response.statusText}): ${await this.errorMessage(response)}`
+        );
+      }
+      const result = await response.json();
+      if (!result.request_id) {
+        throw new Error(
+          "grok: video generation response contained no request_id"
+        );
+      }
+      return { jobId: result.request_id, model };
+    } catch (error) {
+      logger.errors(`${this.name}.createVideoJob fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.createVideoJob failed`),
+        source: `${this.name}.createVideoJob`
+      });
+      throw error;
+    }
+  }
+  async retrieveJob(jobId) {
+    const response = await this.request(`/videos/${jobId}`);
+    if (!response.ok) {
+      const error = new Error(
+        `grok: video status request failed (${response.status} ${response.statusText}): ${await this.errorMessage(response)}`
+      );
+      error.status = response.status;
+      throw error;
+    }
+    return await response.json();
+  }
+  async getVideoStatus(jobId) {
+    let response;
+    try {
+      response = await this.retrieveJob(jobId);
+    } catch (error) {
+      if (error.status === 404) {
+        return { jobId, status: "failed", error: "Job not found" };
+      }
+      throw error;
+    }
+    return {
+      jobId,
+      status: this.mapStatus(response.status),
+      ...response.progress !== void 0 && { progress: response.progress },
+      ...response.error !== void 0 && { error: response.error }
+    };
+  }
+  async getVideoUrl(jobId) {
+    let response;
+    try {
+      response = await this.retrieveJob(jobId);
+    } catch (error) {
+      if (error.status === 404) {
+        throw new Error(`Video job not found: ${jobId}`);
+      }
+      throw error;
+    }
+    const status = this.mapStatus(response.status);
+    if (status === "failed") {
+      throw new Error(
+        `Video generation failed${response.error ? `: ${response.error}` : ""}. Job ID: ${jobId}`
+      );
+    }
+    const url = response.video?.url;
+    if (!url) {
+      throw new Error(
+        `Video is not ready for download. Check status first. Job ID: ${jobId}`
+      );
+    }
+    const usage = buildGrokVideoUsage(response);
+    return {
+      jobId,
+      url,
+      ...usage && { usage }
+    };
+  }
+  /**
+   * Maps Imagine API job statuses onto the generic video status set. The
+   * API reports 'pending' while queued/generating (with a numeric
+   * `progress`), then a terminal 'done' / 'failed' / 'expired'.
+   */
+  mapStatus(apiStatus) {
+    switch (apiStatus) {
+      case "pending":
+      case "queued":
+        return "pending";
+      case "done":
+      case "completed":
+      case "succeeded":
+        return "completed";
+      case "failed":
+      case "expired":
+      case "error":
+      case "cancelled":
+        return "failed";
+      case void 0:
+      default:
+        return "processing";
+    }
+  }
+  /**
+   * Both grok-imagine video models accept a continuous 1–15 integer-second
+   * range. Consumers can use this to render UI without provider knowledge.
+   */
+  availableDurations() {
+    return getGrokVideoDurationOptions(this.model);
+  }
+  /**
+   * Coerce a raw seconds value to the closest valid duration (clamped to
+   * [1, 15] and rounded to whole seconds).
+   */
+  snapDuration(seconds) {
+    return snapToDurationOption(seconds, this.availableDurations());
+  }
+}
+function createGrokVideo(model, apiKey, config) {
+  return new GrokVideoAdapter({ apiKey, ...config }, model);
+}
+function grokVideo(model, config) {
+  const apiKey = getGrokApiKeyFromEnv();
+  return createGrokVideo(model, apiKey, config);
+}
+export {
+  GrokVideoAdapter,
+  createGrokVideo,
+  grokVideo
+};
+//# sourceMappingURL=video.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"video.js","sources":["../../../src/adapters/video.ts"],"sourcesContent":["import { resolveMediaPrompt } from '@tanstack/ai'\nimport { BaseVideoAdapter, snapToDurationOption } from '@tanstack/ai/adapters'\nimport { toRunErrorPayload } from '@tanstack/ai/adapter-internals'\nimport { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'\nimport {\n  getGrokVideoDurationOptions,\n  isImageToVideoOnlyModel,\n  parseGrokVideoSize,\n  validateVideoSize,\n} from '../video/video-provider-options'\nimport type { DurationOptions } from '@tanstack/ai/adapters'\nimport type {\n  ImagePart,\n  MediaInputMetadata,\n  TokenUsage,\n  VideoGenerationOptions,\n  VideoJobResult,\n  VideoStatusResult,\n  VideoUrlResult,\n} from '@tanstack/ai'\nimport type { GrokVideoModel } from '../model-meta'\nimport type {\n  GrokVideoModelDurationByName,\n  GrokVideoModelInputModalitiesByName,\n  GrokVideoModelProviderOptionsByName,\n  GrokVideoModelSizeByName,\n  GrokVideoProviderOptions,\n} from '../video/video-provider-options'\nimport type { GrokClientConfig } from '../utils'\n\n/**\n * Configuration for Grok video adapter.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport interface GrokVideoConfig extends GrokClientConfig {}\n\n/**\n * xAI bills video generation in \"USD ticks\": 10^10 ticks per US dollar\n * (e.g. one grok-imagine-video-1.5 second costs $0.08 = 800_000_000 ticks).\n */\nconst USD_TICKS_PER_DOLLAR = 10_000_000_000\n\n/** Response of POST /v1/videos/generations. */\ninterface GrokVideoCreateResponse {\n  request_id?: string\n}\n\n/** Response of GET /v1/videos/{request_id}. */\ninterface GrokVideoStatusResponse {\n  status?: string\n  progress?: number\n  model?: string\n  video?: {\n    url?: string\n    duration?: number\n  }\n  usage?: {\n    cost_in_usd_ticks?: number\n  }\n  error?: string\n}\n\n/**\n * Convert a TanStack ImagePart to the URL string accepted by xAI's Imagine\n * video 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\nfunction buildGrokVideoUsage(\n  response: GrokVideoStatusResponse,\n): TokenUsage | undefined {\n  const seconds = response.video?.duration\n  const ticks = response.usage?.cost_in_usd_ticks\n  if (seconds === undefined && ticks === undefined) return undefined\n  return {\n    promptTokens: 0,\n    completionTokens: 0,\n    totalTokens: 0,\n    ...(seconds !== undefined && { unitsBilled: seconds }),\n    ...(ticks !== undefined && { cost: ticks / USD_TICKS_PER_DOLLAR }),\n  }\n}\n\n/**\n * Grok Video Generation Adapter (xAI Imagine API)\n *\n * Tree-shakeable adapter for the grok-imagine video models using the\n * async jobs/polling architecture: create a generation request, poll it,\n * then read the completed video URL.\n *\n * `grok-imagine-video` (v1.0) supports text-to-video and image-to-video.\n * `grok-imagine-video-1.5` is image-to-video only — every request needs an\n * image prompt part as the starting frame, and the adapter rejects a\n * text-only prompt with a clear error rather than a raw API 400.\n *\n * The Imagine video endpoints are not part of the OpenAI SDK surface (and\n * xAI rejects the SDK's multipart paths), so requests are plain JSON calls\n * issued with the configured `fetch` (or the global one).\n *\n * @experimental Video generation is an experimental feature and may change.\n *\n * Features:\n * - Async job-based video generation (1–15 second clips with audio)\n * - Aspect-ratio sizing via the \"aspectRatio_resolution\" size template\n *   (e.g. '16:9_720p'), consistent with the grok-imagine image models\n * - Image-to-video via an `image` prompt part (starting frame URL or data URI)\n * - Usage reporting: billed seconds (`unitsBilled`) and exact cost\n */\nexport class GrokVideoAdapter<\n  TModel extends GrokVideoModel,\n> extends BaseVideoAdapter<\n  TModel,\n  GrokVideoProviderOptions,\n  GrokVideoModelProviderOptionsByName,\n  GrokVideoModelSizeByName,\n  GrokVideoModelInputModalitiesByName,\n  GrokVideoModelDurationByName\n> {\n  readonly name = 'grok' as const\n\n  private readonly clientConfig: GrokVideoConfig\n\n  constructor(config: GrokVideoConfig, model: TModel) {\n    super({}, model)\n    this.clientConfig = withGrokDefaults(config)\n  }\n\n  private get fetch(): (\n    input: string,\n    init?: RequestInit,\n  ) => Promise<Response> {\n    return this.clientConfig.fetch ?? fetch\n  }\n\n  private async request(\n    path: string,\n    init?: Omit<RequestInit, 'headers'>,\n  ): Promise<Response> {\n    return await this.fetch(`${this.clientConfig.baseURL}${path}`, {\n      ...init,\n      headers: {\n        'Content-Type': 'application/json',\n        Authorization: `Bearer ${this.clientConfig.apiKey}`,\n      },\n    })\n  }\n\n  /**\n   * Reads the error message out of an Imagine API error body\n   * (`{\"code\": \"...\", \"error\": \"...\"}`), falling back to the raw text.\n   */\n  private async errorMessage(response: Response): Promise<string> {\n    const body = await response.text()\n    try {\n      const parsed: unknown = JSON.parse(body)\n      if (\n        typeof parsed === 'object' &&\n        parsed !== null &&\n        'error' in parsed &&\n        typeof parsed.error === 'string'\n      ) {\n        return parsed.error\n      }\n    } catch {\n      // not JSON — fall through to the raw body\n    }\n    return body\n  }\n\n  async createVideoJob(\n    options: VideoGenerationOptions<\n      GrokVideoProviderOptions,\n      GrokVideoModelSizeByName[TModel],\n      GrokVideoModelDurationByName[TModel]\n    >,\n  ): Promise<VideoJobResult> {\n    const { model, size, modelOptions, logger } = options\n\n    validateVideoSize(model, size)\n\n    // Coerce the requested duration into the model's valid range (1–15s,\n    // integer) instead of rejecting it — `snapDuration` clamps and rounds.\n    // modelOptions wins over the generic `duration`, mirroring the size\n    // precedence below.\n    const rawDuration = modelOptions?.duration ?? options.duration\n    const duration =\n      rawDuration !== undefined ? this.snapDuration(rawDuration) : undefined\n\n    // The interleaved prompt decomposes into verbatim text plus typed media\n    // buckets. The Imagine video endpoint takes a text prompt and an optional\n    // starting frame; reject the modalities it can't consume.\n    const resolved = resolveMediaPrompt(options.prompt)\n    if (resolved.videos.length > 0) {\n      throw new Error(\n        `${this.name}.createVideoJob does not support video prompt parts (model: ${model}).`,\n      )\n    }\n    if (resolved.audios.length > 0) {\n      throw new Error(\n        `${this.name}.createVideoJob does not support audio prompt parts (model: ${model}).`,\n      )\n    }\n    // grok-imagine-video-1.5 is image-to-video only — text-to-video is\n    // rejected by the API, so fail fast with a clear, actionable message\n    // pointing at the model that does support text-to-video.\n    if (resolved.images.length === 0 && isImageToVideoOnlyModel(model)) {\n      throw new Error(\n        `${this.name}: ${model} does not support text-to-video — it is image-to-video only. ` +\n          `Include an image prompt part as the starting frame, or use 'grok-imagine-video' for text-to-video.`,\n      )\n    }\n    if (resolved.images.length > 1) {\n      throw new Error(\n        `${this.name}: ${model} accepts at most one starting-frame image; received ${resolved.images.length}.`,\n      )\n    }\n\n    // Image-to-video: the single image prompt part becomes the starting frame\n    // and the prompt text describes the desired motion. URL sources are\n    // fetched by xAI's servers; data sources are sent as base64 data URIs.\n    const [startFrame] = resolved.images\n\n    // The generic `size` option carries an \"aspectRatio_resolution\" template\n    // (e.g. '16:9_720p') and maps to the Imagine API's `aspect_ratio` /\n    // `resolution` parameters; explicit modelOptions win over the template.\n    const parsedSize = size !== undefined ? parseGrokVideoSize(size) : undefined\n    const request = {\n      model,\n      prompt: resolved.text,\n      ...(startFrame && { image: { url: imagePartToUrl(startFrame) } }),\n      ...(parsedSize && {\n        aspect_ratio: parsedSize.aspectRatio,\n        ...(parsedSize.resolution !== undefined && {\n          resolution: parsedSize.resolution,\n        }),\n      }),\n      ...modelOptions,\n      // Spread after modelOptions so the snapped duration is authoritative\n      // (modelOptions.duration is folded into `duration` via snapDuration above).\n      ...(duration !== undefined && { duration }),\n    }\n\n    try {\n      logger.request(\n        `activity=video.create provider=${this.name} model=${model} size=${size ?? 'default'} duration=${duration ?? 'default'}`,\n        { provider: this.name, model },\n      )\n\n      const response = await this.request('/videos/generations', {\n        method: 'POST',\n        body: JSON.stringify(request),\n      })\n      if (!response.ok) {\n        throw new Error(\n          `grok: video generation request failed (${response.status} ${response.statusText}): ${await this.errorMessage(response)}`,\n        )\n      }\n\n      const result = (await response.json()) as GrokVideoCreateResponse\n      if (!result.request_id) {\n        throw new Error(\n          'grok: video generation response contained no request_id',\n        )\n      }\n      return { jobId: result.request_id, model }\n    } catch (error: unknown) {\n      logger.errors(`${this.name}.createVideoJob fatal`, {\n        error: toRunErrorPayload(error, `${this.name}.createVideoJob failed`),\n        source: `${this.name}.createVideoJob`,\n      })\n      throw error\n    }\n  }\n\n  private async retrieveJob(jobId: string): Promise<GrokVideoStatusResponse> {\n    const response = await this.request(`/videos/${jobId}`)\n    if (!response.ok) {\n      const error = new Error(\n        `grok: video status request failed (${response.status} ${response.statusText}): ${await this.errorMessage(response)}`,\n      )\n      ;(error as { status?: number }).status = response.status\n      throw error\n    }\n    return (await response.json()) as GrokVideoStatusResponse\n  }\n\n  async getVideoStatus(jobId: string): Promise<VideoStatusResult> {\n    let response: GrokVideoStatusResponse\n    try {\n      response = await this.retrieveJob(jobId)\n    } catch (error) {\n      if ((error as { status?: number }).status === 404) {\n        return { jobId, status: 'failed', error: 'Job not found' }\n      }\n      throw error\n    }\n\n    return {\n      jobId,\n      status: this.mapStatus(response.status),\n      ...(response.progress !== undefined && { progress: response.progress }),\n      ...(response.error !== undefined && { error: response.error }),\n    }\n  }\n\n  async getVideoUrl(jobId: string): Promise<VideoUrlResult> {\n    let response: GrokVideoStatusResponse\n    try {\n      response = await this.retrieveJob(jobId)\n    } catch (error) {\n      if ((error as { status?: number }).status === 404) {\n        throw new Error(`Video job not found: ${jobId}`)\n      }\n      throw error\n    }\n\n    const status = this.mapStatus(response.status)\n    if (status === 'failed') {\n      throw new Error(\n        `Video generation failed${response.error ? `: ${response.error}` : ''}. Job ID: ${jobId}`,\n      )\n    }\n    const url = response.video?.url\n    if (!url) {\n      throw new Error(\n        `Video is not ready for download. Check status first. Job ID: ${jobId}`,\n      )\n    }\n\n    const usage = buildGrokVideoUsage(response)\n    return {\n      jobId,\n      url,\n      ...(usage && { usage }),\n    }\n  }\n\n  /**\n   * Maps Imagine API job statuses onto the generic video status set. The\n   * API reports 'pending' while queued/generating (with a numeric\n   * `progress`), then a terminal 'done' / 'failed' / 'expired'.\n   */\n  protected mapStatus(\n    apiStatus: string | undefined,\n  ): 'pending' | 'processing' | 'completed' | 'failed' {\n    switch (apiStatus) {\n      case 'pending':\n      case 'queued':\n        return 'pending'\n      case 'done':\n      case 'completed':\n      case 'succeeded':\n        return 'completed'\n      case 'failed':\n      case 'expired':\n      case 'error':\n      case 'cancelled':\n        return 'failed'\n      case undefined:\n      default:\n        return 'processing'\n    }\n  }\n\n  /**\n   * Both grok-imagine video models accept a continuous 1–15 integer-second\n   * range. Consumers can use this to render UI without provider knowledge.\n   */\n  override availableDurations(): DurationOptions<\n    GrokVideoModelDurationByName[TModel]\n  > {\n    return getGrokVideoDurationOptions(this.model)\n  }\n\n  /**\n   * Coerce a raw seconds value to the closest valid duration (clamped to\n   * [1, 15] and rounded to whole seconds).\n   */\n  override snapDuration(\n    seconds: number,\n  ): GrokVideoModelDurationByName[TModel] | undefined {\n    return snapToDurationOption(seconds, this.availableDurations())\n  }\n}\n\n/**\n * Creates a Grok video adapter with an explicit API key.\n * Type resolution happens here at the call site.\n *\n * @experimental Video generation is an experimental feature and may change.\n *\n * @param model - The model name (e.g., 'grok-imagine-video')\n * @param apiKey - Your xAI API key\n * @param config - Optional additional configuration\n * @returns Configured Grok video adapter instance with resolved types\n *\n * @example\n * ```typescript\n * // grok-imagine-video (v1.0) supports text-to-video.\n * const adapter = createGrokVideo('grok-imagine-video', 'xai-...');\n *\n * const { jobId } = await generateVideo({\n *   adapter,\n *   prompt: 'A beautiful sunset over the ocean',\n *   size: '16:9_720p',\n *   duration: 5\n * });\n * ```\n */\nexport function createGrokVideo<TModel extends GrokVideoModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokVideoConfig, 'apiKey'>,\n): GrokVideoAdapter<TModel> {\n  return new GrokVideoAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Grok video 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 * @experimental Video generation is an experimental feature and may change.\n *\n * @param model - The model name (e.g., 'grok-imagine-video-1.5')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Grok video 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 = grokVideo('grok-imagine-video-1.5');\n *\n * // Image-to-video only: the prompt must carry a starting-frame image part.\n * const { jobId } = await generateVideo({\n *   adapter,\n *   prompt: [\n *     { type: 'text', content: 'Make the cat start playing the piano' },\n *     { type: 'image', source: { type: 'url', value: 'https://example.com/cat.png' } },\n *   ],\n * });\n *\n * // Poll for status\n * const status = await getVideoJobStatus({ adapter, jobId });\n * ```\n */\nexport function grokVideo<TModel extends GrokVideoModel>(\n  model: TModel,\n  config?: Omit<GrokVideoConfig, 'apiKey'>,\n): GrokVideoAdapter<TModel> {\n  const apiKey = getGrokApiKeyFromEnv()\n  return createGrokVideo(model, apiKey, config)\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/index.d.ts

@@ -2,12 +2,15 @@ export { GrokTextAdapter, createGrokText, grokText, type GrokTextConfig, type Gr
 export { createGrokSummarize, grokSummarize, type GrokSummarizeConfig, 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 { GrokVideoAdapter, createGrokVideo, grokVideo, type GrokVideoConfig, } from './adapters/video.js';
+export { GROK_VIDEO_DURATIONS, getGrokVideoDurationOptions, } from './video/video-provider-options.js';
+export type { GrokVideoProviderOptions, GrokVideoModelProviderOptionsByName, GrokVideoModelSizeByName, GrokVideoModelDurationByName, GrokVideoAspectRatio, GrokVideoResolution, GrokVideoSize, } from './video/video-provider-options.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 { GrokChatModelProviderOptionsByName, GrokChatModelToolCapabilitiesByName, GrokModelInputModalitiesByName, ResolveProviderOptions, ResolveInputModalities, GrokChatModel, GrokImageModel, GrokVideoModel, GrokTTSModel, GrokTranscriptionModel, GrokRealtimeModel, } from './model-meta.js';
+export { GROK_CHAT_MODELS, GROK_IMAGE_MODELS, GROK_VIDEO_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';

package/dist/esm/index.js

@@ -1,9 +1,11 @@
 import { GrokTextAdapter, createGrokText, grokText } from "./adapters/text.js";
 import { createGrokSummarize, grokSummarize } from "./adapters/summarize.js";
 import { GrokImageAdapter, createGrokImage, grokImage } from "./adapters/image.js";
+import { GrokVideoAdapter, createGrokVideo, grokVideo } from "./adapters/video.js";
+import { GROK_VIDEO_DURATIONS, getGrokVideoDurationOptions } from "./video/video-provider-options.js";
 import { GrokSpeechAdapter, createGrokSpeech, grokSpeech } from "./adapters/tts.js";
 import { GrokTranscriptionAdapter, createGrokTranscription, grokTranscription } from "./adapters/transcription.js";
-import { GROK_CHAT_MODELS, GROK_IMAGE_MODELS, GROK_REALTIME_MODELS, GROK_TRANSCRIPTION_MODELS, GROK_TTS_MODELS } from "./model-meta.js";
+import { GROK_CHAT_MODELS, GROK_IMAGE_MODELS, GROK_REALTIME_MODELS, GROK_TRANSCRIPTION_MODELS, GROK_TTS_MODELS, GROK_VIDEO_MODELS } from "./model-meta.js";
 import { grokRealtimeToken } from "./realtime/token.js";
 import { grokRealtime } from "./realtime/adapter.js";
 export {
@@ -12,21 +14,27 @@ export {
   GROK_REALTIME_MODELS,
   GROK_TRANSCRIPTION_MODELS,
   GROK_TTS_MODELS,
+  GROK_VIDEO_DURATIONS,
+  GROK_VIDEO_MODELS,
   GrokImageAdapter,
   GrokSpeechAdapter,
   GrokTextAdapter,
   GrokTranscriptionAdapter,
+  GrokVideoAdapter,
   createGrokImage,
   createGrokSpeech,
   createGrokSummarize,
   createGrokText,
   createGrokTranscription,
+  createGrokVideo,
+  getGrokVideoDurationOptions,
   grokImage,
   grokRealtime,
   grokRealtimeToken,
   grokSpeech,
   grokSummarize,
   grokText,
-  grokTranscription
+  grokTranscription,
+  grokVideo
 };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}

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

@@ -46,11 +46,18 @@ export declare const GROK_CHAT_MODELS: readonly ["grok-build-0.1", "grok-4.3"];
  * Grok Image Generation Models
  */
 export declare const GROK_IMAGE_MODELS: readonly ["grok-2-image-1212", "grok-imagine-image", "grok-imagine-image-quality"];
+/**
+ * Grok Video Generation Models (xAI Imagine API)
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare const GROK_VIDEO_MODELS: readonly ["grok-imagine-video", "grok-imagine-video-1.5"];
 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"];
 export type GrokChatModel = (typeof GROK_CHAT_MODELS)[number];
 export type GrokImageModel = (typeof GROK_IMAGE_MODELS)[number];
+export type GrokVideoModel = (typeof GROK_VIDEO_MODELS)[number];
 export type GrokTTSModel = (typeof GROK_TTS_MODELS)[number];
 export type GrokTranscriptionModel = (typeof GROK_TRANSCRIPTION_MODELS)[number];
 export type GrokRealtimeModel = (typeof GROK_REALTIME_MODELS)[number];

package/dist/esm/model-meta.js

@@ -7,6 +7,12 @@ const GROK_IMAGINE_IMAGE = {
 const GROK_IMAGINE_IMAGE_QUALITY = {
   name: "grok-imagine-image-quality"
 };
+const GROK_IMAGINE_VIDEO = {
+  name: "grok-imagine-video"
+};
+const GROK_IMAGINE_VIDEO_1_5 = {
+  name: "grok-imagine-video-1.5"
+};
 const GROK_4_3 = {
   name: "grok-4.3"
 };
@@ -19,6 +25,10 @@ const GROK_IMAGE_MODELS = [
   GROK_IMAGINE_IMAGE.name,
   GROK_IMAGINE_IMAGE_QUALITY.name
 ];
+const GROK_VIDEO_MODELS = [
+  GROK_IMAGINE_VIDEO.name,
+  GROK_IMAGINE_VIDEO_1_5.name
+];
 const GROK_TTS = {
   name: "grok-tts"
 };
@@ -42,6 +52,7 @@ export {
   GROK_IMAGE_MODELS,
   GROK_REALTIME_MODELS,
   GROK_TRANSCRIPTION_MODELS,
-  GROK_TTS_MODELS
+  GROK_TTS_MODELS,
+  GROK_VIDEO_MODELS
 };
 //# sourceMappingURL=model-meta.js.map

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 */\nimport type {\n  GrokBuildProviderOptions,\n  GrokTextProviderOptions,\n} from './text/text-provider-options'\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<GrokProviderToolKind>\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\nexport type GrokProviderToolKind =\n  | 'web_search'\n  | 'x_search'\n  | 'file_search'\n  | 'mcp'\n\nconst GROK_RESPONSES_TOOLS = [\n  'web_search',\n  'x_search',\n  'file_search',\n  'mcp',\n] as const satisfies ReadonlyArray<GrokProviderToolKind>\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\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: GROK_RESPONSES_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: GROK_RESPONSES_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\n/**\n * Grok chat models supported by the Responses adapter.\n */\nexport const GROK_CHAT_MODELS = [GROK_BUILD_0_1.name, GROK_4_3.name] as const\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_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 supported provider tools.\n * Keeps Grok provider-tool factories type-checked against the models that\n * advertise xAI Responses server-side tools.\n */\nexport type GrokChatModelToolCapabilitiesByName = {\n  [GROK_4_3.name]: typeof GROK_4_3.supports.tools\n  [GROK_BUILD_0_1.name]: typeof GROK_BUILD_0_1.supports.tools\n}\n\nexport type GrokProviderOptions = GrokTextProviderOptions\n\n/**\n * Type-only map from Grok chat model name to its provider options type.\n */\nexport type GrokChatModelProviderOptionsByName = {\n  [GROK_4_3.name]: GrokProviderOptions\n  [GROK_BUILD_0_1.name]: GrokBuildProviderOptions\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":"AA4CA,MAAM,eAAe;AAAA,EACnB,MAAM;AAaR;AAGA,MAAM,qBAAqB;AAAA,EACzB,MAAM;AAaR;AAEA,MAAM,6BAA6B;AAAA,EACjC,MAAM;AAaR;AAEA,MAAM,WAAW;AAAA,EACf,MAAM;AAiBR;AAEA,MAAM,iBAAiB;AAAA,EACrB,MAAM;AAiBR;AAKO,MAAM,mBAAmB,CAAC,eAAe,MAAM,SAAS,IAAI;AAK5D,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;"}
+{"version":3,"file":"model-meta.js","sources":["../../src/model-meta.ts"],"sourcesContent":["/**\n * Model metadata interface for documentation and type inference\n */\nimport type {\n  GrokBuildProviderOptions,\n  GrokTextProviderOptions,\n} from './text/text-provider-options'\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<GrokProviderToolKind>\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\nexport type GrokProviderToolKind =\n  | 'web_search'\n  | 'x_search'\n  | 'file_search'\n  | 'mcp'\n\nconst GROK_RESPONSES_TOOLS = [\n  'web_search',\n  'x_search',\n  'file_search',\n  'mcp',\n] as const satisfies ReadonlyArray<GrokProviderToolKind>\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// Imagine API video models. Pricing is per second of generated video\n// (output only); generated videos carry an audio track.\n//\n// grok-imagine-video (v1.0) supports both text-to-video (a starting image is\n// optional) and image-to-video. grok-imagine-video-1.5 is image-to-video\n// only: a starting-frame image is required (the text prompt describes the\n// desired motion) — its text-to-video is rejected by the API.\nconst GROK_IMAGINE_VIDEO = {\n  name: 'grok-imagine-video',\n  supports: {\n    input: ['text', 'image'],\n    output: ['video', 'audio'],\n  },\n  pricing: {\n    input: {\n      normal: 0,\n    },\n    output: {\n      // per second of video\n      normal: 0.05,\n    },\n  },\n} as const satisfies ModelMeta\n\nconst GROK_IMAGINE_VIDEO_1_5 = {\n  name: 'grok-imagine-video-1.5',\n  supports: {\n    input: ['text', 'image'],\n    output: ['video', 'audio'],\n  },\n  pricing: {\n    input: {\n      normal: 0,\n    },\n    output: {\n      // per second of video\n      normal: 0.08,\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: GROK_RESPONSES_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: GROK_RESPONSES_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\n/**\n * Grok chat models supported by the Responses adapter.\n */\nexport const GROK_CHAT_MODELS = [GROK_BUILD_0_1.name, GROK_4_3.name] as const\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/**\n * Grok Video Generation Models (xAI Imagine API)\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport const GROK_VIDEO_MODELS = [\n  GROK_IMAGINE_VIDEO.name,\n  GROK_IMAGINE_VIDEO_1_5.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 GrokVideoModel = (typeof GROK_VIDEO_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_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 supported provider tools.\n * Keeps Grok provider-tool factories type-checked against the models that\n * advertise xAI Responses server-side tools.\n */\nexport type GrokChatModelToolCapabilitiesByName = {\n  [GROK_4_3.name]: typeof GROK_4_3.supports.tools\n  [GROK_BUILD_0_1.name]: typeof GROK_BUILD_0_1.supports.tools\n}\n\nexport type GrokProviderOptions = GrokTextProviderOptions\n\n/**\n * Type-only map from Grok chat model name to its provider options type.\n */\nexport type GrokChatModelProviderOptionsByName = {\n  [GROK_4_3.name]: GrokProviderOptions\n  [GROK_BUILD_0_1.name]: GrokBuildProviderOptions\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":"AA4CA,MAAM,eAAe;AAAA,EACnB,MAAM;AAaR;AAGA,MAAM,qBAAqB;AAAA,EACzB,MAAM;AAaR;AAEA,MAAM,6BAA6B;AAAA,EACjC,MAAM;AAaR;AASA,MAAM,qBAAqB;AAAA,EACzB,MAAM;AAcR;AAEA,MAAM,yBAAyB;AAAA,EAC7B,MAAM;AAcR;AAEA,MAAM,WAAW;AAAA,EACf,MAAM;AAiBR;AAEA,MAAM,iBAAiB;AAAA,EACrB,MAAM;AAiBR;AAKO,MAAM,mBAAmB,CAAC,eAAe,MAAM,SAAS,IAAI;AAK5D,MAAM,oBAAoB;AAAA,EAC/B,aAAa;AAAA,EACb,mBAAmB;AAAA,EACnB,2BAA2B;AAC7B;AAOO,MAAM,oBAAoB;AAAA,EAC/B,mBAAmB;AAAA,EACnB,uBAAuB;AACzB;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/dist/esm/realtime/adapter.d.ts

@@ -1,4 +1,4 @@
-import { RealtimeAdapter } from './realtime-contract.js';
+import { RealtimeAdapter } from '@tanstack/ai';
 import { GrokRealtimeOptions } from './types.js';
 /**
  * Creates a Grok realtime adapter for client-side use.