@ai-sdk/openai 3.0.77 → 3.0.78

package/docs/03-openai.mdx

@@ -54,6 +54,10 @@ You can use the following optional settings to customize the OpenAI provider ins
 
   Use a different URL prefix for API calls, e.g. to use proxy servers.
   The default prefix is `https://api.openai.com/v1`.
+  The default OpenAI model factory (`openai('model-id')`) uses the Responses
+  API. If your custom base URL only supports the Chat Completions API, create
+  chat models with `openai.chat('model-id')` instead, or use the
+  [OpenAI-compatible provider](/providers/openai-compatible-providers).
 
 - **apiKey** _string_
 
@@ -1601,6 +1605,8 @@ for (const part of result.content) {
 You can create models that call the [OpenAI chat API](https://platform.openai.com/docs/api-reference/chat) using the `.chat()` factory method.
 The first argument is the model id, e.g. `gpt-4`.
 The OpenAI chat models support tool calls and some have multi-modal capabilities.
+Use this factory when a custom `baseURL` points at an OpenAI-compatible endpoint
+that implements Chat Completions but not the Responses API.
 
 ```ts
 const model = openai.chat('gpt-5');
@@ -2358,7 +2364,7 @@ const model = openai.image('dall-e-3');
 
 ### Image Editing
 
-OpenAI's `gpt-image-1` model supports powerful image editing capabilities. Pass input images via `prompt.images` to transform, combine, or edit existing images.
+OpenAI's `gpt-image-*` models support powerful image editing capabilities. Pass input images via `prompt.images` to transform, combine, or edit existing images.
 
 #### Basic Image Editing
 
@@ -2368,7 +2374,7 @@ Transform an existing image using text prompts:
 const imageBuffer = readFileSync('./input-image.png');
 
 const { images } = await generateImage({
-  model: openai.image('gpt-image-1'),
+  model: openai.image('gpt-image-2'),
   prompt: {
     text: 'Turn the cat into a dog but retain the style of the original image',
     images: [imageBuffer],
@@ -2385,7 +2391,7 @@ const image = readFileSync('./input-image.png');
 const mask = readFileSync('./mask.png'); // Transparent areas = edit regions
 
 const { images } = await generateImage({
-  model: openai.image('gpt-image-1'),
+  model: openai.image('gpt-image-2'),
   prompt: {
     text: 'A sunlit indoor lounge area with a pool containing a flamingo',
     images: [image],
@@ -2396,7 +2402,7 @@ const { images } = await generateImage({
 
 #### Background Removal
 
-Remove the background from an image by setting `background` to `transparent`:
+Remove the background from an image by setting `background` to `transparent` on a model that supports transparent backgrounds:
 
 ```ts
 import { openai, type OpenAIImageModelEditOptions } from '@ai-sdk/openai';
@@ -2405,7 +2411,7 @@ import { generateImage } from 'ai';
 const imageBuffer = readFileSync('./input-image.png');
 
 const { images } = await generateImage({
-  model: openai.image('gpt-image-1'),
+  model: openai.image('gpt-image-1.5'),
   prompt: {
     text: 'do not change anything',
     images: [imageBuffer],
@@ -2421,7 +2427,7 @@ const { images } = await generateImage({
 
 #### Multi-Image Combining
 
-Combine multiple reference images into a single output. `gpt-image-1` supports up to 16 input images:
+Combine multiple reference images into a single output. `gpt-image-*` models support up to 16 input images:
 
 ```ts
 const cat = readFileSync('./cat.png');
@@ -2430,7 +2436,7 @@ const owl = readFileSync('./owl.png');
 const bear = readFileSync('./bear.png');
 
 const { images } = await generateImage({
-  model: openai.image('gpt-image-1'),
+  model: openai.image('gpt-image-2'),
   prompt: {
     text: 'Combine these animals into a group photo, retaining the original style',
     images: [cat, dog, owl, bear],
@@ -2440,21 +2446,22 @@ const { images } = await generateImage({
 
 <Note>
   Input images can be provided as `Buffer`, `ArrayBuffer`, `Uint8Array`, or
-  base64-encoded strings. For `gpt-image-1`, each image should be a `png`,
-  `webp`, or `jpg` file less than 50MB.
+  base64-encoded strings. For `gpt-image-*` models, each image should be a
+  `png`, `webp`, or `jpg` file less than 50MB.
 </Note>
 
 ### Model Capabilities
 
 | Model              | Sizes                           |
 | ------------------ | ------------------------------- |
+| `gpt-image-2`      | 1024x1024, 1536x1024, 1024x1536 |
 | `gpt-image-1.5`    | 1024x1024, 1536x1024, 1024x1536 |
 | `gpt-image-1-mini` | 1024x1024, 1536x1024, 1024x1536 |
 | `gpt-image-1`      | 1024x1024, 1536x1024, 1024x1536 |
 | `dall-e-3`         | 1024x1024, 1792x1024, 1024x1792 |
 | `dall-e-2`         | 256x256, 512x512, 1024x1024     |
 
-You can pass optional `providerOptions` to the image model. These are prone to change by OpenAI and are model dependent. For example, the `gpt-image-1` model supports the `quality` option:
+You can pass optional `providerOptions` to the image model. These are prone to change by OpenAI and are model dependent. For example, the `gpt-image-*` models support the `quality` option:
 
 ```ts
 import {
@@ -2464,7 +2471,7 @@ import {
 import { generateImage } from 'ai';
 
 const { image, providerMetadata } = await generateImage({
-  model: openai.image('gpt-image-1.5'),
+  model: openai.image('gpt-image-2'),
   prompt: 'A salamander at sunrise in a forest pond in the Seychelles.',
   providerOptions: {
     openai: { quality: 'high' } satisfies OpenAIImageModelGenerationOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/openai",
-  "version": "3.0.77",
+  "version": "3.0.78",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

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

@@ -1037,11 +1037,13 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
       isShellProviderExecuted,
     } = await this.getArgs(options);
 
+    const url = this.config.url({
+      path: '/responses',
+      modelId: this.modelId,
+    });
+
     const { responseHeaders, value: response } = await postJsonToApi({
-      url: this.config.url({
-        path: '/responses',
-        modelId: this.modelId,
-      }),
+      url,
       headers: combineHeaders(this.config.headers(), options.headers),
       body: {
         ...body,
@@ -1133,8 +1135,18 @@ export class OpenAIResponsesLanguageModel implements LanguageModelV3 {
 
             // handle failed chunk parsing / validation:
             if (!chunk.success) {
+              const error = isOpenAIChatCompletionChunk(chunk.rawValue)
+                ? createOpenAIResponsesChatCompletionsMismatchError({
+                    value: chunk.rawValue,
+                    cause: chunk.error,
+                    url,
+                    requestBodyValues: body,
+                    responseHeaders,
+                  })
+                : chunk.error;
+
               finishReason = { unified: 'error', raw: undefined };
-              controller.enqueue({ type: 'error', error: chunk.error });
+              controller.enqueue({ type: 'error', error });
               return;
             }
 
@@ -2137,6 +2149,50 @@ function isTextDeltaChunk(
   return chunk.type === 'response.output_text.delta';
 }
 
+function isOpenAIChatCompletionChunk(value: unknown): boolean {
+  const chunk = asRecord(value);
+
+  return (
+    chunk != null &&
+    Array.isArray(chunk.choices) &&
+    typeof chunk.type !== 'string'
+  );
+}
+
+function createOpenAIResponsesChatCompletionsMismatchError({
+  value,
+  cause,
+  url,
+  requestBodyValues,
+  responseHeaders,
+}: {
+  value: unknown;
+  cause: unknown;
+  url: string;
+  requestBodyValues: unknown;
+  responseHeaders?: Record<string, string>;
+}): APICallError {
+  return new APICallError({
+    message:
+      'Received a Chat Completions stream while using the OpenAI Responses API. ' +
+      "The default OpenAI provider model uses the Responses API. If your custom baseURL targets a Chat Completions-compatible endpoint, use openai.chat('model-id') or createOpenAI(...).chat('model-id') instead. " +
+      'You can also use @ai-sdk/openai-compatible for OpenAI-compatible providers.',
+    url,
+    requestBodyValues,
+    responseHeaders,
+    responseBody: JSON.stringify(value),
+    cause,
+    data: value,
+    isRetryable: false,
+  });
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value != null
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
 function isResponseOutputItemDoneChunk(
   chunk: OpenAIResponsesChunk,
 ): chunk is OpenAIResponsesChunk & { type: 'response.output_item.done' } {