@ai-sdk/openai 3.0.129 → 3.0.131

package/docs/03-openai.mdx

@@ -276,7 +276,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.
@@ -2357,7 +2357,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="11"
 import { openai } from '@ai-sdk/openai';
@@ -2390,7 +2390,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": "3.0.129",
+  "version": "3.0.131",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "3.0.19",
-    "@ai-sdk/provider-utils": "4.0.60"
+    "@ai-sdk/provider-utils": "4.0.62"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

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

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

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

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

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/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

@@ -8,6 +8,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 SharedV3Warning,
 } from '@ai-sdk/provider';
 import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
   convertToBase64,
   isNonNullable,
   parseJSON,
@@ -36,6 +39,7 @@ import type {
   OpenAIResponsesCustomToolCallOutput,
   OpenAIResponsesFunctionCallOutput,
   OpenAIResponsesInput,
+  OpenAIResponsesPromptCacheBreakpoint,
   OpenAIResponsesReasoning,
   OpenAIResponsesWebSearchCall,
 } from './openai-responses-api';
@@ -114,7 +118,7 @@ async function convertFunctionToolResultOutput({
   warnings,
 }: {
   output: LanguageModelV3ToolResultOutput;
-  promptCacheBreakpoint?: OpenAIPromptCacheBreakpoint;
+  promptCacheBreakpoint?: OpenAIResponsesPromptCacheBreakpoint;
   providerOptionsName: string;
   warnings: Array<SharedV3Warning>;
 }): Promise<OpenAIResponsesFunctionCallOutput['output']> {
@@ -344,14 +348,12 @@ function collectCompleteParallelToolResultGroups({
   return completeGroups;
 }
 
-type OpenAIPromptCacheBreakpoint = { mode: 'explicit' };
-
 function getPromptCacheBreakpoint(
   providerOptions: SharedV3ProviderOptions | undefined,
   providerOptionsName: string,
-): OpenAIPromptCacheBreakpoint | undefined {
+): OpenAIResponsesPromptCacheBreakpoint | undefined {
   return providerOptions?.[providerOptionsName]?.promptCacheBreakpoint as
-    | OpenAIPromptCacheBreakpoint
+    | OpenAIResponsesPromptCacheBreakpoint
     | undefined;
 }
 
@@ -363,7 +365,7 @@ function getScalarToolResultPromptCacheBreakpoint({
   output: LanguageModelV3ToolResultOutput;
   toolResultProviderOptions: SharedV3ProviderOptions | undefined;
   providerOptionsName: string;
-}): OpenAIPromptCacheBreakpoint | undefined {
+}): OpenAIResponsesPromptCacheBreakpoint | undefined {
   return output.type === 'content'
     ? undefined
     : (getPromptCacheBreakpoint(output.providerOptions, providerOptionsName) ??
@@ -1524,11 +1526,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
 >;