@ai-sdk/openai 4.0.98 → 4.0.100

package/docs/03-openai.mdx

@@ -1,17 +1,61 @@
 ---
 title: OpenAI
-description: Learn how to use the OpenAI provider for the AI SDK.
+description: Learn how to use OpenAI with AI Gateway and the direct provider.
 ---
 
 # OpenAI Provider
 
 The [OpenAI](https://openai.com/) provider contains language model support for the OpenAI responses, chat, and completion APIs, as well as embedding model support for the OpenAI embeddings API.
+You can use OpenAI models through [AI Gateway](/providers/ai-sdk-providers/ai-gateway) (recommended) or connect directly with `@ai-sdk/openai`.
 
-## Setup
+```ts provider="openai" model="openai/gpt-6-astra"
+import { generateText } from 'ai';
+__PROVIDER_IMPORT__;
 
-The OpenAI provider is available in the `@ai-sdk/openai` module. You can install it with
+const { text } = await generateText({
+  model: __MODEL__,
+  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+});
+
+console.log(text);
+```
+
+## Using AI Gateway
+
+The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install `ai`:
+
+<InstallPackages packages="ai" />
+
+Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment:
+
+```bash
+export AI_GATEWAY_API_KEY=your_api_key_here
+```
 
-<InstallPackages packages="@ai-sdk/openai" />
+Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments).
+See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models.
+
+Gateway feature and provider-option support depends on the model and the provider serving the request. See [Gateway provider options](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options).
+
+## Using `@ai-sdk/openai`
+
+For direct access to OpenAI, install `ai` and `@ai-sdk/openai`:
+
+<InstallPackages packages="ai @ai-sdk/openai" />
+
+Set your OpenAI API credential in the `OPENAI_API_KEY` environment variable:
+
+```bash
+export OPENAI_API_KEY=your_api_key_here
+```
+
+AI Gateway does not expose every API in `@ai-sdk/openai`. Use the direct provider for provider-specific APIs or custom connection settings.
+
+<Note>
+  The following sections document the direct `@ai-sdk/openai` provider,
+  including its model factories and settings. Gateway model and feature
+  availability can differ.
+</Note>
 
 ## Provider Instance
 
@@ -239,7 +283,7 @@ The following provider options are available:
   OpenAI structured outputs have several
   [limitations](https://openai.com/index/introducing-structured-outputs-in-the-api),
   in particular around the [supported
-  schemas](https://platform.openai.com/docs/guides/structured-outputs/supported-schemas),
+  schemas](https://developers.openai.com/api/docs/guides/structured-outputs#supported-schemas),
   and are therefore opt-in. For example, optional schema properties are not
   supported. You need to change Zod `.nullish()` and `.optional()` to
   `.nullable()`.
@@ -274,7 +318,7 @@ The following provider options are available:
   A cache key for manual prompt caching control. Used by OpenAI to cache responses for similar requests to optimize your cache hit rates.
 
 - **promptCacheOptions** _object_
-  Configures prompt caching for GPT-5.6 and later models. `mode` can be `'implicit'` or `'explicit'`, and `ttl` currently only supports `'30m'`. In explicit mode, only content blocks marked with a prompt cache breakpoint are cached.
+  Configures prompt caching for GPT-5.6 and later models. `mode` can be `'implicit'` or `'explicit'`. `ttl` sets the minimum cache lifetime: `'30m'` (default) or `'12h'`. 12-hour writes are billed at a higher rate, and `usage.raw.input_tokens_details.cache_write_tokens_details` splits cache writes into `ttl_30m_tokens` and `ttl_12h_tokens`. Set `prewarm` to `true` to write the prompt to the cache without generating output. In explicit mode, only content blocks marked with a prompt cache breakpoint are cached.
 
 - **promptCacheRetention** _'in_memory' | '24h'_
   The legacy retention policy for models before GPT-5.6. Set to `'24h'` to enable extended prompt caching on supported models. For GPT-5.6 and later models, use `promptCacheOptions.ttl` instead.
@@ -2814,7 +2858,7 @@ including `gpt-4o` and `gpt-4o-mini`.
   not need to be explicitly enabled.
 - You can use the response `usage` to access the number of prompt tokens that were a cache hit via `usage.inputTokenDetails.cacheReadTokens`.
 - For GPT-5.6 and later models, `usage.inputTokenDetails.cacheWriteTokens` reports tokens written to the cache.
-- For GPT-5.6 and later models, `promptCacheOptions.ttl` sets a minimum cache lifetime of 30 minutes. Earlier models generally retain in-memory prefixes for 5-10 minutes of inactivity, up to one hour.
+- For GPT-5.6 and later models, `promptCacheOptions.ttl` sets a minimum cache lifetime of 30 minutes. Chat models only support `'30m'`. The 12-hour lifetime is available on [Responses models](#responses-models). Earlier models generally retain in-memory prefixes for 5-10 minutes of inactivity, up to one hour.
 
 ```ts highlight="9"
 import { openai } from '@ai-sdk/openai';
@@ -2847,7 +2891,7 @@ const { text, usage } = await generateText({
 console.log('Cached tokens:', usage.inputTokenDetails.cacheReadTokens);
 ```
 
-GPT-5.6 and later models support explicit cache breakpoints on text, image, and file content blocks. Set a request-level cache key and mark the end of each reusable prefix with `promptCacheBreakpoint`:
+GPT-5.6 and later models support explicit cache breakpoints on text, image, and file content blocks. Set a request-level cache key and mark the end of each reusable prefix with `promptCacheBreakpoint`. With Responses models, a breakpoint can set its own `ttl` (for example `{ mode: 'explicit', ttl: '12h' }`) to override the request-level `promptCacheOptions.ttl`:
 
 ```ts highlight="9-12,20-28"
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "4.0.98",
+  "version": "4.0.100",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,8 +35,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.31",
-    "@ai-sdk/provider-utils": "5.0.64"
+    "@ai-sdk/provider": "4.0.32",
+    "@ai-sdk/provider-utils": "5.0.66"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.4",

package/src/chat/openai-chat-api.ts

@@ -199,7 +199,7 @@ export const openaiChatChunkSchema = lazySchema(() =>
           })
           .nullish(),
       }),
-      openaiErrorDataSchema,
+      openaiErrorDataSchema(),
     ]),
   ),
 );

package/src/chat/openai-chat-language-model.ts

@@ -532,8 +532,9 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
 
     let toolCallTracker: StreamingToolCallTracker;
 
+    // A clean end without the provider's completion signal is interrupted.
     let finishReason: LanguageModelV4FinishReason = {
-      unified: 'other',
+      unified: 'interrupted',
       raw: undefined,
     };
     let usage: OpenAIChatUsage | undefined = undefined;

package/src/completion/openai-completion-api.ts

@@ -70,7 +70,7 @@ export const openaiCompletionChunkSchema = lazySchema(() =>
           })
           .nullish(),
       }),
-      openaiErrorDataSchema,
+      openaiErrorDataSchema(),
     ]),
   ),
 );

package/src/completion/openai-completion-language-model.ts

@@ -272,8 +272,9 @@ export class OpenAICompletionLanguageModel implements LanguageModelV4 {
       responseHeaders,
     });
 
+    // A clean end without the provider's completion signal is interrupted.
     let finishReason: LanguageModelV4FinishReason = {
-      unified: 'other',
+      unified: 'interrupted',
       raw: undefined,
     };
     const providerMetadata: SharedV4ProviderMetadata = { openai: {} };

package/src/files/openai-files.ts

@@ -17,6 +17,7 @@ import {
   createBinaryStreamResponseHandler,
   createJsonResponseHandler,
   deleteFromApi,
+  encodePathSegment,
   getFromApi,
   parseProviderOptions,
   postFormDataToApi,
@@ -44,17 +45,6 @@ interface OpenAIFilesConfig {
 
 type OpenAIFilesResponse = InferSchema<typeof openaiFilesResponseSchema>;
 
-function encodePathSegment(value: string): string {
-  const encodedValue = encodeURIComponent(value);
-
-  // URL parsing normalizes both literal and percent-encoded dot segments.
-  return encodedValue === '.'
-    ? '%252E'
-    : encodedValue === '..'
-      ? '%252E%252E'
-      : encodedValue;
-}
-
 export class OpenAIFiles implements FilesV4 {
   readonly specificationVersion = 'v4';
 

package/src/image/openai-image-model-options.ts

@@ -49,45 +49,46 @@ export function getMaxImagesPerCall(modelId: OpenAIImageModelId): number {
   );
 }
 
-const baseImageModelOptionsObject = z.object({
-  /**
-   * Quality of the generated image(s).
-   *
-   * Valid values: `standard`, `hd`, `low`, `medium`, `high`, `xhigh`, `max`, `auto`.
-   * `xhigh` and `max` are supported by GPT Image 2.5 models.
-   */
-  quality: z
-    .enum(['standard', 'hd', 'low', 'medium', 'high', 'xhigh', 'max', 'auto'])
-    .optional(),
-
-  /**
-   * Background behavior for the generated image(s).
-   *
-   * If `transparent`, the output format must support transparency
-   * (i.e. `png` or `webp`).
-   */
-  background: z.enum(['transparent', 'opaque', 'auto']).optional(),
-
-  /**
-   * Format in which the generated image(s) are returned.
-   */
-  outputFormat: z.enum(['png', 'jpeg', 'webp']).optional(),
-
-  /**
-   * Compression level (0-100) for the generated image(s). Applies to the
-   * `jpeg` and `webp` output formats.
-   */
-  outputCompression: z.number().int().min(0).max(100).optional(),
-
-  /**
-   * A unique identifier representing your end-user, which can help OpenAI
-   * to monitor and detect abuse.
-   */
-  user: z.string().optional(),
-});
+const baseImageModelOptionsObject = () =>
+  z.object({
+    /**
+     * Quality of the generated image(s).
+     *
+     * Valid values: `standard`, `hd`, `low`, `medium`, `high`, `xhigh`, `max`, `auto`.
+     * `xhigh` and `max` are supported by GPT Image 2.5 models.
+     */
+    quality: z
+      .enum(['standard', 'hd', 'low', 'medium', 'high', 'xhigh', 'max', 'auto'])
+      .optional(),
+
+    /**
+     * Background behavior for the generated image(s).
+     *
+     * If `transparent`, the output format must support transparency
+     * (i.e. `png` or `webp`).
+     */
+    background: z.enum(['transparent', 'opaque', 'auto']).optional(),
+
+    /**
+     * Format in which the generated image(s) are returned.
+     */
+    outputFormat: z.enum(['png', 'jpeg', 'webp']).optional(),
+
+    /**
+     * Compression level (0-100) for the generated image(s). Applies to the
+     * `jpeg` and `webp` output formats.
+     */
+    outputCompression: z.number().int().min(0).max(100).optional(),
+
+    /**
+     * A unique identifier representing your end-user, which can help OpenAI
+     * to monitor and detect abuse.
+     */
+    user: z.string().optional(),
+  });
 
 export const openaiImageModelOptions = lazySchema(() =>
-  zodSchema(baseImageModelOptionsObject),
+  zodSchema(baseImageModelOptionsObject()),
 );
 
 export type OpenAIImageModelOptions = InferSchema<
@@ -96,7 +97,7 @@ export type OpenAIImageModelOptions = InferSchema<
 
 export const openaiImageModelGenerationOptions = lazySchema(() =>
   zodSchema(
-    baseImageModelOptionsObject.extend({
+    baseImageModelOptionsObject().extend({
       /**
        * Style of the generated image. `vivid` produces hyper-real and
        * dramatic images; `natural` produces more subdued, less hyper-real
@@ -119,7 +120,7 @@ export type OpenAIImageModelGenerationOptions = InferSchema<
 
 export const openaiImageModelEditOptions = lazySchema(() =>
   zodSchema(
-    baseImageModelOptionsObject.extend({
+    baseImageModelOptionsObject().extend({
       /**
        * Fidelity of the output image(s) to the input image(s).
        */

package/src/live/openai-realtime-model-live.ts

@@ -4,6 +4,8 @@ import {
   type Experimental_RealtimeModelV4SessionConfig as RealtimeModelV4SessionConfig,
 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
   createJsonResponseHandler,
   postJsonToApi,
 } from '@ai-sdk/provider-utils';
@@ -20,10 +22,17 @@ import type { OpenAIRealtimeModelConfig } from '../realtime/openai-realtime-mode
 
 export type OpenAIRealtimeModelLiveConfig = OpenAIRealtimeModelConfig;
 
-const webRTCSessionSchema = z.object({
-  session: z.object({ id: z.string().min(1) }),
-  transport: z.object({ type: z.literal('webrtc'), sdp: z.string().min(1) }),
-});
+const webRTCSessionSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      session: z.object({ id: z.string().min(1) }),
+      transport: z.object({
+        type: z.literal('webrtc'),
+        sdp: z.string().min(1),
+      }),
+    }),
+  ),
+);
 
 export class OpenAIRealtimeModelLive implements RealtimeModelV4 {
   readonly specificationVersion = 'v4' as const;

package/src/openai-batch.ts

@@ -35,7 +35,7 @@ import {
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import {
-  openaiErrorDataSchema,
+  openaiErrorDataSchemaValidator,
   openaiFailedResponseHandler,
 } from './openai-error';
 import type { OpenAIConfig } from './openai-config';
@@ -663,7 +663,7 @@ async function convertOpenAIErrorResponse({
 }): Promise<BatchV4Error> {
   const result = await safeValidateTypes({
     value: body,
-    schema: openaiErrorDataSchema,
+    schema: openaiErrorDataSchemaValidator,
   });
 
   if (!result.success) {

package/src/openai-decision-model.ts

@@ -6,6 +6,8 @@ import {
   type Experimental_DecisionModelV4Input as DecisionModelV4Input,
 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
   combineHeaders,
   convertUint8ArrayToBase64,
   detectMediaType,
@@ -27,54 +29,63 @@ import { openaiDecisionModelOptions } from './openai-decision-model-options';
 
 export type OpenAIDecisionModelId = 'gpt-6-luna' | (string & {});
 
-const probability = z.number().min(0).max(1);
-const responseSchema = z.object({
-  model: z.string().nullish(),
-  usage: z
-    .object({
-      input_tokens: z.number().nullish(),
-      input_tokens_details: z
+const probability = () => z.number().min(0).max(1);
+const responseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      model: z.string().nullish(),
+      usage: z
         .object({
-          cached_tokens: z.number().nullish(),
-          cache_write_tokens: z.number().nullish(),
+          input_tokens: z.number().nullish(),
+          input_tokens_details: z
+            .object({
+              cached_tokens: z.number().nullish(),
+              cache_write_tokens: z.number().nullish(),
+            })
+            .nullish(),
+          output_tokens: z.number().nullish(),
+          output_tokens_details: z
+            .object({
+              reasoning_tokens: z.number().nullish(),
+            })
+            .nullish(),
+          total_tokens: z.number().nullish(),
         })
         .nullish(),
-      output_tokens: z.number().nullish(),
-      output_tokens_details: z
-        .object({
-          reasoning_tokens: z.number().nullish(),
-        })
-        .nullish(),
-      total_tokens: z.number().nullish(),
-    })
-    .nullish(),
-  answers: z.array(
-    z.discriminatedUnion('type', [
-      z.object({ type: z.literal('refusal'), name: z.string().nullable() }),
-      z.object({
-        type: z.literal('predicate'),
-        name: z.string(),
-        probability,
-      }),
-      z.object({
-        type: z.literal('choice'),
-        name: z.string(),
-        choice: z.string(),
-        confidence: probability.nullish(),
-        probabilities: z.array(z.object({ value: z.string(), probability })),
-      }),
-      z.object({
-        type: z.literal('score'),
-        name: z.string(),
-        score: z.number(),
-        confidence: probability.nullish(),
-        probabilities: z.array(
-          z.object({ value: z.number().int().nonnegative(), probability }),
-        ),
-      }),
-    ]),
+      answers: z.array(
+        z.discriminatedUnion('type', [
+          z.object({ type: z.literal('refusal'), name: z.string().nullable() }),
+          z.object({
+            type: z.literal('predicate'),
+            name: z.string(),
+            probability: probability(),
+          }),
+          z.object({
+            type: z.literal('choice'),
+            name: z.string(),
+            choice: z.string(),
+            confidence: probability().nullish(),
+            probabilities: z.array(
+              z.object({ value: z.string(), probability: probability() }),
+            ),
+          }),
+          z.object({
+            type: z.literal('score'),
+            name: z.string(),
+            score: z.number(),
+            confidence: probability().nullish(),
+            probabilities: z.array(
+              z.object({
+                value: z.number().int().nonnegative(),
+                probability: probability(),
+              }),
+            ),
+          }),
+        ]),
+      ),
+    }),
   ),
-});
+);
 
 export class DecisionOpenAIModel implements DecisionModelV4 {
   readonly specificationVersion = 'v4';

package/src/openai-error.ts

@@ -1,22 +1,30 @@
 import { z } from 'zod/v4';
-import { createJsonErrorResponseHandler } from '@ai-sdk/provider-utils';
+import {
+  lazySchema,
+  zodSchema,
+  createJsonErrorResponseHandler,
+} from '@ai-sdk/provider-utils';
 
-export const openaiErrorDataSchema = z.object({
-  error: z.object({
-    message: z.string(),
+export const openaiErrorDataSchema = () =>
+  z.object({
+    error: z.object({
+      message: z.string(),
 
-    // The additional information below is handled loosely to support
-    // OpenAI-compatible providers that have slightly different error
-    // responses:
-    type: z.string().nullish(),
-    param: z.any().nullish(),
-    code: z.union([z.string(), z.number()]).nullish(),
-  }),
-});
+      // The additional information below is handled loosely to support
+      // OpenAI-compatible providers that have slightly different error
+      // responses:
+      type: z.string().nullish(),
+      param: z.any().nullish(),
+      code: z.union([z.string(), z.number()]).nullish(),
+    }),
+  });
+export const openaiErrorDataSchemaValidator = lazySchema(() =>
+  zodSchema(openaiErrorDataSchema()),
+);
 
-export type OpenAIErrorData = z.infer<typeof openaiErrorDataSchema>;
+export type OpenAIErrorData = z.infer<ReturnType<typeof openaiErrorDataSchema>>;
 
 export const openaiFailedResponseHandler = createJsonErrorResponseHandler({
-  errorSchema: openaiErrorDataSchema,
+  errorSchema: openaiErrorDataSchemaValidator,
   errorToMessage: data => data.error.message,
 });

package/src/responses/convert-openai-responses-usage.ts

@@ -9,6 +9,12 @@ export type OpenAIResponsesUsage = JSONObject & {
     | (JSONObject & {
         cached_tokens?: number | null;
         cache_write_tokens?: number | null;
+        cache_write_tokens_details?:
+          | (JSONObject & {
+              ttl_30m_tokens?: number | null;
+              ttl_12h_tokens?: number | null;
+            })
+          | null;
         orchestration_input_tokens?: number | null;
         orchestration_input_cached_tokens?: number | null;
       })

package/src/responses/convert-to-openai-responses-input.ts

@@ -8,6 +8,9 @@ import {
   type SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
   convertToBase64,
   getTopLevelMediaType,
   isNonNullable,
@@ -39,6 +42,7 @@ import type {
   OpenAIResponsesCustomToolCallOutput,
   OpenAIResponsesFunctionCallOutput,
   OpenAIResponsesInput,
+  OpenAIResponsesPromptCacheBreakpoint,
   OpenAIResponsesReasoning,
   OpenAIResponsesToolCaller,
   OpenAIResponsesWebSearchCall,
@@ -144,7 +148,7 @@ async function convertFunctionToolResultOutput({
   output: LanguageModelV4ToolResultOutput;
   toolName: string;
   outputSchemaToolNames: Set<string> | undefined;
-  promptCacheBreakpoint?: OpenAIPromptCacheBreakpoint;
+  promptCacheBreakpoint?: OpenAIResponsesPromptCacheBreakpoint;
   providerOptionsName: string;
   warnings: Array<SharedV4Warning>;
 }): Promise<OpenAIResponsesFunctionCallOutput['output']> {
@@ -389,14 +393,12 @@ function collectCompleteParallelToolResultGroups({
   return completeGroups;
 }
 
-type OpenAIPromptCacheBreakpoint = { mode: 'explicit' };
-
 function getPromptCacheBreakpoint(
   providerOptions: SharedV4ProviderOptions | undefined,
   providerOptionsName: string,
-): OpenAIPromptCacheBreakpoint | undefined {
+): OpenAIResponsesPromptCacheBreakpoint | undefined {
   return providerOptions?.[providerOptionsName]?.promptCacheBreakpoint as
-    | OpenAIPromptCacheBreakpoint
+    | OpenAIResponsesPromptCacheBreakpoint
     | undefined;
 }
 
@@ -408,7 +410,7 @@ function getScalarToolResultPromptCacheBreakpoint({
   output: LanguageModelV4ToolResultOutput;
   toolResultProviderOptions: SharedV4ProviderOptions | undefined;
   providerOptionsName: string;
-}): OpenAIPromptCacheBreakpoint | undefined {
+}): OpenAIResponsesPromptCacheBreakpoint | undefined {
   return output.type === 'content'
     ? undefined
     : (getPromptCacheBreakpoint(output.providerOptions, providerOptionsName) ??
@@ -1854,11 +1856,15 @@ export async function convertToOpenAIResponsesInput({
   return { input, warnings };
 }
 
-const openaiResponsesReasoningProviderOptionsSchema = z.object({
-  itemId: z.string().nullish(),
-  reasoningEncryptedContent: z.string().nullish(),
-});
+const openaiResponsesReasoningProviderOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      itemId: z.string().nullish(),
+      reasoningEncryptedContent: z.string().nullish(),
+    }),
+  ),
+);
 
-export type OpenAIResponsesReasoningProviderOptions = z.infer<
+export type OpenAIResponsesReasoningProviderOptions = InferSchema<
   typeof openaiResponsesReasoningProviderOptionsSchema
 >;