@ai-sdk/openai 4.0.46 → 4.0.49

package/docs/03-openai.mdx

@@ -1956,40 +1956,60 @@ The metadata includes the following fields:
 ### Text Batches
 
 <Note type="warning">
-  Text batch APIs are experimental and may change in future releases.
+  Text batch support is experimental and the API may change in patch releases.
 </Note>
 
-The OpenAI provider supports the [Batch API](https://developers.openai.com/api/docs/guides/batch) for text generation.
+The OpenAI provider supports asynchronous text generation through the
+[Batch API](https://developers.openai.com/api/docs/guides/batch). Use the
+experimental text batch APIs to start a batch, poll its status, and stream its
+results:
 
 ```ts
 import { openai } from '@ai-sdk/openai';
 import {
-  experimental_startTextBatch as startTextBatch,
   experimental_getBatchResults as getBatchResults,
   experimental_getBatchStatus as getBatchStatus,
+  experimental_startTextBatch as startTextBatch,
 } from 'ai';
+import { setTimeout } from 'node:timers/promises';
 
 const model = openai('gpt-4.1-nano');
 
 const batch = await startTextBatch({
   model,
   requests: [
-    { id: 'france', prompt: 'What is the capital of France?' },
-    { id: 'germany', prompt: 'What is the capital of Germany?' },
+    { id: 'capital-france', prompt: 'What is the capital of France?' },
+    { id: 'capital-germany', prompt: 'What is the capital of Germany?' },
   ],
 });
 
-// Persist `batch` and check its status later, or poll for status updates.
-const { status } = await getBatchStatus({ model, batch });
+let status = batch.status;
+while (status === 'pending') {
+  await setTimeout(60_000);
+  ({ status } = await getBatchStatus({ model, batch }));
+}
 
-if (status !== 'pending') {
-  for await (const result of getBatchResults({ model, batch })) {
-    console.log(result);
+for await (const item of getBatchResults({ model, batch })) {
+  if (item.status === 'succeeded') {
+    console.log(item.id, item.text);
+  } else {
+    console.error(item.id, item.error);
   }
 }
 ```
 
-Starting a batch returns a serializable reference that can be persisted and used to retrieve the batch results later, or poll for status updates.
+`startTextBatch` returns a serializable batch reference. Persist this reference
+to check the batch status or retrieve its results from another process. Results
+can arrive in a different order from the input requests, so match each result by
+its `id`.
+
+#### Webhooks
+
+<Note>
+  The OpenAI Batch API does not support per-batch webhooks. When you provide a
+  `webhookUrl`, the provider returns an unsupported warning and starts the batch
+  without a webhook.
+</Note>
 
 ### Chat Models
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "4.0.46",
+  "version": "4.0.49",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -35,16 +35,16 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.7",
-    "@ai-sdk/provider-utils": "5.0.29"
+    "@ai-sdk/provider": "4.0.8",
+    "@ai-sdk/provider-utils": "5.0.32"
   },
   "devDependencies": {
+    "@ai-sdk/test-server": "2.0.1",
     "@types/node": "22.19.19",
+    "@vercel/ai-tsconfig": "0.0.0",
     "tsup": "^8.5.1",
     "typescript": "5.8.3",
-    "zod": "3.25.76",
-    "@ai-sdk/test-server": "2.0.1",
-    "@vercel/ai-tsconfig": "0.0.0"
+    "zod": "3.25.76"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

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

@@ -40,7 +40,7 @@ export function convertOpenAIChatUsage(
     },
     outputTokens: {
       total: completionTokens,
-      text: completionTokens - reasoningTokens,
+      text: Math.max(0, completionTokens - reasoningTokens),
       reasoning: reasoningTokens,
     },
     raw: usage,

package/src/chat/convert-to-openai-chat-messages.ts

@@ -13,7 +13,11 @@ import {
 } from '@ai-sdk/provider-utils';
 
 function serializeToolCallArguments(input: unknown): string {
-  return JSON.stringify(input === undefined ? {} : input);
+  return JSON.stringify(
+    typeof input === 'object' && input !== null && !Array.isArray(input)
+      ? input
+      : {},
+  );
 }
 
 type OpenAIPromptCacheBreakpoint = { mode: 'explicit' };

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

@@ -26,7 +26,10 @@ import {
 } from '@ai-sdk/provider-utils';
 import { openaiFailedResponseHandler } from '../openai-error';
 import { getOpenAILanguageModelCapabilities } from '../openai-language-model-capabilities';
-import { throwIfOpenAIStreamErrorBeforeOutput } from '../openai-stream-error';
+import {
+  createOpenAIProviderStreamError,
+  throwIfOpenAIStreamErrorBeforeOutput,
+} from '../openai-stream-error';
 import {
   convertOpenAIChatUsage,
   type OpenAIChatUsage,
@@ -509,7 +512,11 @@ export class OpenAIChatLanguageModel implements LanguageModelV4 {
             // handle error chunks:
             if ('error' in value) {
               finishReason = { unified: 'error', raw: undefined };
-              controller.enqueue({ type: 'error', error: value.error });
+              controller.enqueue({
+                type: 'error',
+                error:
+                  createOpenAIProviderStreamError(value.error) ?? value.error,
+              });
               return;
             }
 

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

@@ -21,7 +21,10 @@ import {
   type ParseResult,
 } from '@ai-sdk/provider-utils';
 import { openaiFailedResponseHandler } from '../openai-error';
-import { throwIfOpenAIStreamErrorBeforeOutput } from '../openai-stream-error';
+import {
+  createOpenAIProviderStreamError,
+  throwIfOpenAIStreamErrorBeforeOutput,
+} from '../openai-stream-error';
 import {
   convertOpenAICompletionUsage,
   type OpenAICompletionUsage,
@@ -302,7 +305,11 @@ export class OpenAICompletionLanguageModel implements LanguageModelV4 {
             // handle error chunks:
             if ('error' in value) {
               finishReason = { unified: 'error', raw: undefined };
-              controller.enqueue({ type: 'error', error: value.error });
+              controller.enqueue({
+                type: 'error',
+                error:
+                  createOpenAIProviderStreamError(value.error) ?? value.error,
+              });
               return;
             }
 

package/src/embedding/openai-embedding-model.ts

@@ -5,6 +5,7 @@ import {
 import {
   combineHeaders,
   createJsonResponseHandler,
+  EXPERIMENTAL_EMBEDDING_MODEL_MAX_INPUT_BYTES_PER_CALL,
   parseProviderOptions,
   postJsonToApi,
   serializeModelOptions,
@@ -23,6 +24,7 @@ export class OpenAIEmbeddingModel implements EmbeddingModelV4 {
   readonly specificationVersion = 'v4';
   readonly modelId: OpenAIEmbeddingModelId;
   readonly maxEmbeddingsPerCall = 2048;
+  readonly [EXPERIMENTAL_EMBEDDING_MODEL_MAX_INPUT_BYTES_PER_CALL] = 300_000;
   readonly supportsParallelCalls = true;
 
   private readonly config: OpenAIConfig;

package/src/openai-responses-batch.ts

@@ -1,6 +1,6 @@
 import {
-  EmptyResponseBodyError,
   InvalidArgumentError,
+  InvalidResponseDataError,
   type Experimental_BatchLanguageModelV4 as BatchLanguageModelV4,
   type Experimental_BatchV4StartOptions as BatchV4StartOptions,
   type Experimental_BatchV4StartResult as BatchV4StartResult,
@@ -15,19 +15,18 @@ import {
 import {
   combineHeaders,
   convertAsyncIteratorToReadableStream,
+  createJsonLinesResponseHandler,
   createJsonResponseHandler,
   getFromApi,
   lazySchema,
-  parseJSON,
+  normalizeBatchRequestCounts,
   postJsonToApi,
   postToApi,
   safeValidateTypes,
-  validateTypes,
   WORKFLOW_DESERIALIZE,
   WORKFLOW_SERIALIZE,
   zodSchema,
   type InferSchema,
-  type ResponseHandler,
 } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import {
@@ -44,6 +43,7 @@ import {
 } from './responses/openai-responses-api';
 import { OpenAIResponsesLanguageModel } from './responses/openai-responses-language-model';
 import type { OpenAIResponsesModelId } from './responses/openai-responses-language-model-options';
+import type { ResponsesReasoningProviderMetadata } from './responses/openai-responses-provider-metadata';
 
 const openaiBatchEndpoint = '/v1/responses';
 const openaiBatchInputFileExpiresAfterSeconds = 48 * 60 * 60;
@@ -133,7 +133,19 @@ class OpenAIResponsesBatch {
     options: BatchV4StartOptions<OpenAIBatchRequest>,
   ): Promise<BatchV4StartResult> {
     const fileParts: string[] = [];
-    const warnings: BatchV4StartResult['warnings'] = [];
+    const warnings: BatchV4StartResult['warnings'] =
+      options.webhookUrl == null
+        ? []
+        : [
+            {
+              warning: {
+                type: 'unsupported',
+                feature: 'webhookUrl',
+                details:
+                  'The OpenAI Batch API does not support per-batch webhook URLs.',
+              },
+            },
+          ];
 
     for (const request of options.requests) {
       const preparedRequest = await this.options.prepareRequest(request);
@@ -229,7 +241,9 @@ class OpenAIResponsesBatch {
   ): Promise<ReadableStream<BatchV4ItemResult<LanguageModelV4GenerateResult>>> {
     const batch = await this.retrieveBatch(options);
 
-    if (convertOpenAIBatchStatus(batch).status === 'pending') {
+    const batchStatus = convertOpenAIBatchStatus(batch);
+
+    if (batchStatus.status === 'pending') {
       throw new InvalidArgumentError({
         argument: 'batchId',
         message: `OpenAI batch "${options.batchId}" is not complete.`,
@@ -239,6 +253,14 @@ class OpenAIResponsesBatch {
     const fileIds = [batch.output_file_id, batch.error_file_id].filter(
       (fileId): fileId is string => fileId != null,
     );
+
+    if (batchStatus.status === 'completed' && fileIds.length === 0) {
+      throw new InvalidResponseDataError({
+        data: batch,
+        message: `OpenAI batch "${options.batchId}" completed without batch output.`,
+      });
+    }
+
     const iterator = this.iterateBatchResults({ fileIds, options });
 
     return convertAsyncIteratorToReadableStream(iterator);
@@ -270,20 +292,22 @@ class OpenAIResponsesBatch {
     options: BatchV4OperationOptions;
   }): AsyncGenerator<BatchV4ItemResult<LanguageModelV4GenerateResult>> {
     for (const fileId of fileIds) {
-      const { value: stream } = await getFromApi({
+      const { value: lines } = await getFromApi({
         url: this.getUrl(`/files/${encodeURIComponent(fileId)}/content`),
         headers: combineHeaders(
           this.options.config.headers?.(),
           options.headers,
         ),
         failedResponseHandler: openaiFailedResponseHandler,
-        successfulResponseHandler: rawStreamResponseHandler,
+        successfulResponseHandler: createJsonLinesResponseHandler(
+          openaiBatchResultLineSchema,
+        ),
         abortSignal: options.abortSignal,
         fetch: this.options.config.fetch,
         validateUrl: false,
       });
 
-      for await (const line of parseJsonLines(stream)) {
+      for await (const line of lines) {
         yield await this.convertResultLine(line);
       }
     }
@@ -456,24 +480,15 @@ function convertOpenAIRequestCounts(
   const completed = counts?.completed;
   const failed = counts?.failed;
 
-  if (
-    total == null ||
-    completed == null ||
-    failed == null ||
-    total < 0 ||
-    completed < 0 ||
-    failed < 0 ||
-    completed + failed > total
-  ) {
-    return undefined;
-  }
-
-  return {
+  return normalizeBatchRequestCounts({
     total,
-    pending: total - completed - failed,
+    pending:
+      total != null && completed != null && failed != null
+        ? total - completed - failed
+        : undefined,
     completed,
     failed,
-  };
+  });
 }
 
 function convertUnixTimestamp(value: number | null | undefined) {
@@ -518,11 +533,23 @@ async function convertOpenAIErrorResponse({
 async function convertOpenAIResponsesBatchResponse(
   body: unknown,
 ): Promise<OpenAIBatchResponseConversion> {
-  const response = await validateTypes({
+  const validation = await safeValidateTypes({
     value: body,
     schema: openaiResponsesResponseSchema,
   });
 
+  if (!validation.success) {
+    return {
+      success: false,
+      error: {
+        message: 'OpenAI returned an invalid Responses batch result.',
+        code: 'invalid_response',
+      },
+    };
+  }
+
+  const response = validation.value;
+
   if (response.error != null) {
     return {
       success: false,
@@ -552,25 +579,59 @@ async function convertOpenAIResponsesBatchResponse(
   const logprobs: Array<NonNullable<OpenAIResponsesLogprobs>> = [];
 
   for (const part of response.output) {
-    if (part.type === 'message') {
-      for (const contentPart of part.content) {
-        content.push({ type: 'text', text: contentPart.text });
-        if (contentPart.logprobs != null) {
-          logprobs.push(contentPart.logprobs);
+    switch (part.type) {
+      case 'reasoning': {
+        const summaries =
+          part.summary.length > 0
+            ? part.summary
+            : [{ type: 'summary_text' as const, text: '' }];
+
+        for (const summary of summaries) {
+          content.push({
+            type: 'reasoning',
+            text: summary.text,
+            providerMetadata: {
+              openai: {
+                itemId: part.id,
+                reasoningEncryptedContent: part.encrypted_content ?? null,
+              } satisfies ResponsesReasoningProviderMetadata,
+            },
+          });
         }
+        break;
       }
-    } else if (
-      part.type === 'function_call' ||
-      part.type === 'custom_tool_call'
-    ) {
-      return {
-        success: false,
-        error: {
-          message:
-            'OpenAI returned a tool call, but tool calls are not supported in AI SDK text batches.',
-          code: 'unsupported_tool_call',
-        },
-      };
+
+      case 'message': {
+        for (const contentPart of part.content) {
+          content.push({ type: 'text', text: contentPart.text });
+          if (contentPart.logprobs != null) {
+            logprobs.push(contentPart.logprobs);
+          }
+        }
+        break;
+      }
+
+      case 'function_call':
+      case 'custom_tool_call':
+        return {
+          success: false,
+          error: {
+            message:
+              'OpenAI returned a tool call, but tool calls are not supported in AI SDK text batches.',
+            code: 'unsupported_content',
+          },
+        };
+
+      default:
+        return {
+          success: false,
+          error: {
+            message:
+              `OpenAI returned an unsupported "${part.type}" output item ` +
+              'in an AI SDK text batch.',
+            code: 'unsupported_content',
+          },
+        };
     }
   }
 
@@ -612,64 +673,3 @@ async function convertOpenAIResponsesBatchResponse(
     },
   };
 }
-
-const rawStreamResponseHandler: ResponseHandler<
-  ReadableStream<Uint8Array>
-> = async ({ response }) => {
-  if (response.body == null) {
-    throw new EmptyResponseBodyError();
-  }
-
-  return { value: response.body };
-};
-
-async function* parseJsonLines(
-  stream: ReadableStream<Uint8Array>,
-): AsyncGenerator<OpenAIBatchResultLine> {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder();
-  let buffer = '';
-  let finished = false;
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-
-      if (done) {
-        finished = true;
-        buffer += decoder.decode();
-        break;
-      }
-
-      buffer += decoder.decode(value, { stream: true });
-
-      let lineEnd = buffer.indexOf('\n');
-      while (lineEnd !== -1) {
-        const line = buffer.slice(0, lineEnd).replace(/\r$/, '');
-        buffer = buffer.slice(lineEnd + 1);
-
-        if (line.trim().length > 0) {
-          yield await parseJSON({
-            text: line,
-            schema: openaiBatchResultLineSchema,
-          });
-        }
-
-        lineEnd = buffer.indexOf('\n');
-      }
-    }
-
-    const finalLine = buffer.replace(/\r$/, '');
-    if (finalLine.trim().length > 0) {
-      yield await parseJSON({
-        text: finalLine,
-        schema: openaiBatchResultLineSchema,
-      });
-    }
-  } finally {
-    if (!finished) {
-      await reader.cancel().catch(() => {});
-    }
-    reader.releaseLock();
-  }
-}

package/src/openai-stream-error.ts

@@ -1,13 +1,41 @@
 import { APICallError } from '@ai-sdk/provider';
-import type { ParseResult } from '@ai-sdk/provider-utils';
+import {
+  createProviderStreamError,
+  type ParseResult,
+  type ProviderStreamError,
+} from '@ai-sdk/provider-utils';
 
 type StreamError = {
   message: string;
   code?: string | number | null;
   type?: string | null;
-  frame: unknown;
 };
 
+/**
+ * Converts an OpenAI stream error frame into provider-owned metadata that AI
+ * SDK Core can normalize without duplicating OpenAI error-code semantics.
+ */
+export function createOpenAIProviderStreamError(
+  frame: unknown,
+): ProviderStreamError | undefined {
+  const streamError = parseStreamError(frame);
+
+  if (streamError == null) {
+    return undefined;
+  }
+
+  const statusCode = getStatusCode(streamError);
+
+  return createProviderStreamError({
+    message: streamError.message,
+    type: streamError.type ?? undefined,
+    code: streamError.code ?? undefined,
+    statusCode,
+    isRetryable: isRetryableStreamError(streamError, statusCode),
+    data: frame,
+  });
+}
+
 export async function throwIfOpenAIStreamErrorBeforeOutput<T>({
   stream,
   getError,
@@ -154,17 +182,18 @@ function createOpenAIStreamError({
   requestBodyValues: unknown;
   responseHeaders?: Record<string, string>;
 }): APICallError {
-  const streamError = parseStreamError(frame);
+  const streamError = createOpenAIProviderStreamError(frame);
   return new APICallError({
     message:
       streamError?.message ??
       'OpenAI stream failed before any output was generated',
     url,
     requestBodyValues,
-    statusCode: streamError == null ? 500 : getStatusCode(streamError),
+    statusCode: streamError?.statusCode ?? 500,
     responseHeaders,
     responseBody: JSON.stringify(frame),
     data: frame,
+    isRetryable: streamError?.isRetryable,
   });
 }
 
@@ -184,7 +213,6 @@ function parseStreamError(frame: unknown): StreamError | undefined {
           message: responseError.message,
           code: getStringOrNumber(responseError.code),
           type: 'response.failed',
-          frame,
         }
       : undefined;
   }
@@ -200,21 +228,14 @@ function parseStreamError(frame: unknown): StreamError | undefined {
         message: error.message,
         code: getStringOrNumber(error.code),
         type: typeof error.type === 'string' ? error.type : undefined,
-        frame,
       }
     : undefined;
 }
 
 function getStatusCode(error: StreamError): number {
-  if (typeof error.code === 'number' && isHttpErrorStatusCode(error.code)) {
-    return error.code;
-  }
-
-  if (typeof error.code === 'string' && /^\d{3}$/.test(error.code)) {
-    const numericCode = Number(error.code);
-    if (isHttpErrorStatusCode(numericCode)) {
-      return numericCode;
-    }
+  const explicitStatusCode = getHttpStatusCode(error.code);
+  if (explicitStatusCode != null) {
+    return explicitStatusCode;
   }
 
   const discriminator = [error.code, error.type]
@@ -260,3 +281,35 @@ function getStringOrNumber(value: unknown): string | number | undefined {
 function isHttpErrorStatusCode(value: number): boolean {
   return Number.isInteger(value) && value >= 400 && value <= 599;
 }
+
+function getHttpStatusCode(value: string | number | null | undefined) {
+  const statusCode =
+    typeof value === 'string' && /^\d{3}$/.test(value) ? Number(value) : value;
+
+  return typeof statusCode === 'number' && isHttpErrorStatusCode(statusCode)
+    ? statusCode
+    : undefined;
+}
+
+function isRetryableStatusCode(statusCode: number): boolean {
+  return (
+    statusCode === 408 ||
+    statusCode === 409 ||
+    statusCode === 429 ||
+    statusCode >= 500
+  );
+}
+
+function isRetryableStreamError(
+  error: StreamError,
+  statusCode: number,
+): boolean {
+  if (
+    error.code === 'insufficient_quota' ||
+    error.type === 'insufficient_quota'
+  ) {
+    return false;
+  }
+
+  return isRetryableStatusCode(statusCode);
+}