OpenAI Provider

The OpenAI provider contains language model support for the OpenAI responses, chat, and completion APIs, as well as embedding model support for the OpenAI embeddings API.

Setup

The OpenAI provider is available in the @ai-sdk/openai module. You can install it with

pnpm add @ai-sdk/openai

Provider Instance

You can import the default provider instance openai from @ai-sdk/openai:

1
import { openai } from '@ai-sdk/openai';

If you need a customized setup, you can import createOpenAI from @ai-sdk/openai and create a provider instance with your settings:

1
import { createOpenAI } from '@ai-sdk/openai';
2

3
const openai = createOpenAI({
4
  // custom settings, e.g.
5
  headers: {
6
    'header-name': 'header-value',
7
  },
8
});

You can use the following optional settings to customize the OpenAI provider instance:

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://api.openai.com/v1.

• apiKey string

  API key that is being sent using the Authorization header. It defaults to the OPENAI_API_KEY environment variable.

• name string

  The provider name. You can set this when using OpenAI compatible providers to change the model provider property. Defaults to openai.

• organization string

  OpenAI Organization.

• project string

  OpenAI project.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

Language Models

The OpenAI provider instance is a function that you can invoke to create a language model:

1
const model = openai('gpt-5');

It automatically selects the correct API based on the model id. You can also pass additional settings in the second argument:

1
const model = openai('gpt-5', {
2
  // additional settings
3
});

The available options depend on the API that's automatically chosen for the model (see below). If you want to explicitly select a specific model API, you can use .responses, .chat, or .completion.

Example

You can use OpenAI language models to generate text with the generateText function:

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const { text } = await generateText({
5
  model: openai('gpt-5'),
6
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
7
});

OpenAI language models can also be used in the streamText, generateObject, and streamObject functions (see AI SDK Core).

Responses Models

You can use the OpenAI responses API with the openai(modelId) or openai.responses(modelId) factory methods. It is the default API that is used by the OpenAI provider (since AI SDK 5).

1
const model = openai('gpt-5');

Further configuration can be done using OpenAI provider options. You can validate the provider options using the OpenAIResponsesProviderOptions type.

1
import { openai, OpenAIResponsesProviderOptions } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const result = await generateText({
5
  model: openai('gpt-5'), // or openai.responses('gpt-5')
6
  providerOptions: {
7
    openai: {
8
      parallelToolCalls: false,
9
      store: false,
10
      user: 'user_123',
11
      // ...
12
    } satisfies OpenAIResponsesProviderOptions,
13
  },
14
  // ...
15
});

The following provider options are available:

• parallelToolCalls boolean Whether to use parallel tool calls. Defaults to true.

• store boolean

  Whether to store the generation. Defaults to true.

• maxToolCalls integer The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored.

• metadata Record<string, string> Additional metadata to store with the generation.

• conversation string The ID of the OpenAI Conversation to continue. You must create a conversation first via the OpenAI API. Cannot be used in conjunction with previousResponseId. Defaults to undefined.

• previousResponseId string The ID of the previous response. You can use it to continue a conversation. Defaults to undefined.

• instructions string Instructions for the model. They can be used to change the system or developer message when continuing a conversation using the previousResponseId option. Defaults to undefined.

• user string A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Defaults to undefined.

• reasoningEffort 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' Reasoning effort for reasoning models. Defaults to medium. If you use providerOptions to set the reasoningEffort option, this model setting will be ignored.

• reasoningEffortUpdate 'low' | 'medium' | 'high' | 'xhigh' | 'max' Updates the reasoning effort for GPT-6 and later models starting with the current response without changing the request-level effort. Use this with previousResponseId to preserve the original prompt prefix for caching. Configuration updates require standard, single-agent mode and cannot be combined with automatic truncation.

• reasoningMode 'standard' | 'pro' Controls how much model work GPT-5.6 performs before returning a final answer. 'standard' is the default. Use 'pro' for difficult tasks where quality matters more than latency and token usage.

• reasoningContext 'auto' | 'current_turn' | 'all_turns' Controls which available reasoning items GPT-5.6 can reuse. 'auto' uses the model default, 'current_turn' excludes reasoning from earlier turns, and 'all_turns' makes compatible earlier reasoning available. The effective context is returned as providerMetadata.openai.reasoningContext.

• reasoningSummary 'auto' | 'detailed' Controls whether the model returns its reasoning process. Set to 'auto' for a condensed summary, 'detailed' for more comprehensive reasoning. Defaults to undefined (no reasoning summaries). When enabled, reasoning summaries appear in the stream as events with type 'reasoning' and in non-streaming responses within the reasoning field.

• strictJsonSchema boolean Whether to use strict JSON schema validation. Defaults to false.

• serviceTier 'auto' | 'flex' | 'priority' | 'default' Service tier for the request. Set to 'flex' for 50% cheaper processing at the cost of increased latency (available for o3, o4-mini, and gpt-5 models). Set to 'priority' for faster processing with Enterprise access (available for gpt-4, gpt-5, gpt-5-mini, o3, o4-mini; gpt-5-nano is not supported).

  Defaults to 'auto'.

• textVerbosity 'low' | 'medium' | 'high' Controls the verbosity of the model's response. Lower values result in more concise responses, while higher values result in more verbose responses. Defaults to 'medium'.

• include Array<string> Specifies additional content to include in the response. Supported values: ['file_search_call.results'] for including file search results in responses. ['message.output_text.logprobs'] for logprobs. Defaults to undefined.

• truncation string The truncation strategy to use for the model response.

  • Auto: If the input to this Response exceeds the model's context window size, the model will truncate the response to fit the context window by dropping items from the beginning of the conversation.
  • disabled (default): If the input size will exceed the context window size for a model, the request will fail with a 400 error.

• promptCacheKey string 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.

• 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.

• safetyIdentifier string A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user.

The OpenAI responses provider also returns provider-specific metadata:

1
const { usage, providerMetadata } = await generateText({
2
  model: openai.responses('gpt-5'),
3
});
4

5
const openaiMetadata = providerMetadata?.openai as
6
  | {
7
      responseId?: string;
8
      reasoningContext?: string;
9
      usage?: { cacheWriteTokens?: number };
10
    }
11
  | undefined;
12
console.log('Cache reads:', usage.cachedInputTokens);
13
console.log('Reasoning tokens:', usage.reasoningTokens);
14
console.log('Cache writes:', openaiMetadata?.usage?.cacheWriteTokens);

The following OpenAI-specific metadata is returned:

• responseId string The ID of the response. Can be used to continue a conversation.

• reasoningContext string The effective persisted-reasoning context returned by GPT-5.6.

• usage.cacheWriteTokens number The number of input tokens written to the prompt cache.

Changing Reasoning Effort Mid-Conversation

GPT-6 and later models can change reasoning effort between responses without changing the request-level reasoningEffort setting. The provider sends reasoningEffortUpdate as an OpenAI configuration_update input item before the next user message. Keeping the request-level effort unchanged preserves the original prompt prefix for prompt caching.

1
import { openai, type OpenAIResponsesProviderOptions } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const first = await generateText({
5
  model: openai.responses('gpt-6-astra'),
6
  prompt: 'Draft a database migration plan.',
7
  providerOptions: {
8
    openai: {
9
      reasoningEffort: 'low',
10
    } satisfies OpenAIResponsesProviderOptions,
11
  },
12
});
13

14
const previousResponseId = first.providerMetadata?.openai.responseId as
15
  | string
16
  | undefined;
17

18
if (!previousResponseId) {
19
  throw new Error('OpenAI did not return a response ID.');
20
}
21

22
const second = await generateText({
23
  model: openai.responses('gpt-6-astra'),
24
  prompt: 'Analyze the failure modes and propose rollback steps.',
25
  providerOptions: {
26
    openai: {
27
      previousResponseId,
28
      reasoningEffort: 'low',
29
      reasoningEffortUpdate: 'high',
30
    } satisfies OpenAIResponsesProviderOptions,
31
  },
32
});

The response metadata continues to report the request-level reasoning effort, not the effective effort selected by reasoningEffortUpdate. Configuration updates are not supported with reasoningMode: 'pro' or truncation: 'auto'.

Reasoning Output

For reasoning models like gpt-5, you can enable reasoning summaries to see the model's thought process. Different models support different summarizers—for example, o4-mini supports detailed summaries. Set reasoningSummary: "auto" to automatically receive the richest level available.

1
import { openai } from '@ai-sdk/openai';
2
import { streamText } from 'ai';
3

4
const result = streamText({
5
  model: openai('gpt-5'),
6
  prompt: 'Tell me about the Mission burrito debate in San Francisco.',
7
  providerOptions: {
8
    openai: {
9
      reasoningSummary: 'detailed', // 'auto' for condensed or 'detailed' for comprehensive
10
    },
11
  },
12
});
13

14
for await (const part of result.fullStream) {
15
  if (part.type === 'reasoning') {
16
    console.log(`Reasoning: ${part.textDelta}`);
17
  } else if (part.type === 'text-delta') {
18
    process.stdout.write(part.textDelta);
19
  }
20
}

For non-streaming calls with generateText, the reasoning summaries are available in the reasoning field of the response:

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const result = await generateText({
5
  model: openai('gpt-5'),
6
  prompt: 'Tell me about the Mission burrito debate in San Francisco.',
7
  providerOptions: {
8
    openai: {
9
      reasoningSummary: 'auto',
10
    },
11
  },
12
});
13
console.log('Reasoning:', result.reasoning);

Learn more about reasoning summaries in the OpenAI documentation.

Verbosity Control

You can control the length and detail of model responses using the textVerbosity parameter:

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const result = await generateText({
5
  model: openai('gpt-5-mini'),
6
  prompt: 'Write a poem about a boy and his first pet dog.',
7
  providerOptions: {
8
    openai: {
9
      textVerbosity: 'low', // 'low' for concise, 'medium' (default), or 'high' for verbose
10
    },
11
  },
12
});

The textVerbosity parameter scales output length without changing the underlying prompt:

• 'low': Produces terse, minimal responses
• 'medium': Balanced detail (default)
• 'high': Verbose responses with comprehensive detail

Web Search Tool

The OpenAI responses API supports web search through the openai.tools.webSearch tool.

1
const result = await generateText({
2
  model: openai('gpt-5'),
3
  prompt: 'What happened in San Francisco last week?',
4
  tools: {
5
    web_search: openai.tools.webSearch({
6
      // optional configuration:
7
      externalWebAccess: true,
8
      searchContextSize: 'high',
9
      userLocation: {
10
        type: 'approximate',
11
        city: 'San Francisco',
12
        region: 'California',
13
      },
14
      filters: {
15
        allowedDomains: ['sfchronicle.com', 'sfgate.com'],
16
        blockedDomains: ['example.com'],
17
      },
18
    }),
19
  },
20
  // Force web search tool (optional):
21
  toolChoice: { type: 'tool', toolName: 'web_search' },
22
});
23

24
// URL sources
25
const sources = result.sources;

The web search tool supports the following configuration options:

• externalWebAccess boolean - Whether to use external web access for fetching live content. Defaults to true.
• searchContextSize 'low' | 'medium' | 'high' - Controls the amount of context used for the search. Higher values provide more comprehensive results but may have higher latency and cost.
• userLocation - Optional location information to provide geographically relevant results. Includes type (always 'approximate'), country, city, region, and timezone.
• filters - Optional filter configuration to restrict search results.
  • allowedDomains string[] - Up to 100 allowed domains for the search.
  • blockedDomains string[] - Up to 100 blocked domains for the search.

Omit the HTTP or HTTPS prefix from domain filters. Subdomains of configured domains are automatically included or excluded.

For detailed information on configuration options see the OpenAI Web Search Tool documentation.

File Search Tool

The OpenAI responses API supports file search through the openai.tools.fileSearch tool.

You can force the use of the file search tool by setting the toolChoice parameter to { type: 'tool', toolName: 'file_search' }.

1
const result = await generateText({
2
  model: openai('gpt-5'),
3
  prompt: 'What does the document say about user authentication?',
4
  tools: {
5
    file_search: openai.tools.fileSearch({
6
      vectorStoreIds: ['vs_123'],
7
      // configuration below is optional:
8
      maxNumResults: 5,
9
      filters: {
10
        key: 'author',
11
        type: 'eq',
12
        value: 'Jane Smith',
13
      },
14
      ranking: {
15
        ranker: 'auto',
16
        scoreThreshold: 0.5,
17
      },
18
    }),
19
  },
20
  providerOptions: {
21
    openai: {
22
      // optional: include results
23
      include: ['file_search_call.results'],
24
    } satisfies OpenAIResponsesProviderOptions,
25
  },
26
});

Image Generation Tool

OpenAI's Responses API supports multi-modal image generation as a provider-defined tool. Availability is restricted to specific models (for example, gpt-5 variants).

You can use the image tool with either generateText or streamText:

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const result = await generateText({
5
  model: openai('gpt-5'),
6
  prompt:
7
    'Generate an image of an echidna swimming across the Mozambique channel.',
8
  tools: {
9
    image_generation: openai.tools.imageGeneration({ outputFormat: 'webp' }),
10
  },
11
});
12

13
for (const toolResult of result.staticToolResults) {
14
  if (toolResult.toolName === 'image_generation') {
15
    const base64Image = toolResult.output.result;
16
  }
17
}

1
import { openai } from '@ai-sdk/openai';
2
import { streamText } from 'ai';
3

4
const result = streamText({
5
  model: openai('gpt-5'),
6
  prompt:
7
    'Generate an image of an echidna swimming across the Mozambique channel.',
8
  tools: {
9
    image_generation: openai.tools.imageGeneration({
10
      outputFormat: 'webp',
11
      quality: 'low',
12
    }),
13
  },
14
});
15

16
for await (const part of result.fullStream) {
17
  if (part.type == 'tool-result' && !part.dynamic) {
18
    const base64Image = part.output.result;
19
  }
20
}

For complete details on model availability, image quality controls, supported sizes, and tool-specific parameters, refer to the OpenAI documentation:

• Image generation overview and models: OpenAI Image Generation
• Image generation tool parameters (background, size, quality, format, etc.): Image Generation Tool Options

Code Interpreter Tool

The OpenAI responses API supports the code interpreter tool through the openai.tools.codeInterpreter tool. This allows models to write and execute Python code.

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const result = await generateText({
5
  model: openai('gpt-5'),
6
  prompt: 'Write and run Python code to calculate the factorial of 10',
7
  tools: {
8
    code_interpreter: openai.tools.codeInterpreter({
9
      // optional configuration:
10
      container: {
11
        fileIds: ['file-123', 'file-456'], // optional file IDs to make available
12
      },
13
    }),
14
  },
15
});

The code interpreter tool can be configured with:

• container: Either a container ID string or an object with fileIds to specify uploaded files that should be available to the code interpreter

Local Shell Tool

The OpenAI responses API support the local shell tool for Codex models through the openai.tools.localShell tool. Local shell is a tool that allows agents to run shell commands locally on a machine you or the user provides.

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const result = await generateText({
5
  model: openai.responses('gpt-5-codex'),
6
  tools: {
7
    local_shell: openai.tools.localShell({
8
      execute: async ({ action }) => {
9
        // ... your implementation, e.g. sandbox access ...
10
        return { output: stdout };
11
      },
12
    }),
13
  },
14
  prompt: 'List the files in my home directory.',
15
  stopWhen: stepCountIs(2),
16
});

Async Tool Calling

GPT-6 Astra and later Responses models support async tool calling. An async tool lets the model continue generating independent output after issuing the call instead of waiting for its result. Your application still executes the tool and sends its result in a later request using the original tool call ID.

Enable async calling on a function tool with providerOptions.openai.async:

1
import { openai, type OpenAIToolOptions } from '@ai-sdk/openai';
2
import { generateText, tool } from 'ai';
3
import { z } from 'zod';
4

5
const result = await generateText({
6
  model: openai.responses('gpt-6-astra'),
7
  tools: {
8
    getWeather: tool({
9
      description: 'Get the weather for a city.',
10
      inputSchema: z.object({ city: z.string() }),
11
      outputSchema: z.object({
12
        city: z.string(),
13
        temperatureC: z.number(),
14
      }),
15
      providerOptions: {
16
        openai: { async: true } satisfies OpenAIToolOptions,
17
      },
18
    }),
19
  },
20
  prompt:
21
    'Start the weather lookup for Paris, then list three general packing essentials without waiting.',
22
});

The generated tool call exposes the provider marker as providerMetadata.openai.async. Use providerMetadata.openai.responseId as the next request's previousResponseId, and submit the result in a tool message with the original toolCallId.

With streamText, OpenAI can continue streaming text after the completed tool-call part. Use the tool's onInputAvailable callback to start work as soon as that part arrives. If execute returns the same already-running promise, tool execution overlaps the rest of the model stream. Omit execute when the job should outlive the current generation and submit its result in a later request.

Async calling applies to directly called function tools. It does not apply to hosted tools such as web search or code interpreter.

Image Inputs

The OpenAI Responses API supports Image inputs for appropriate models. You can pass Image files as part of the message content using the 'image' type:

1
const result = await generateText({
2
  model: openai('gpt-5'),
3
  messages: [
4
    {
5
      role: 'user',
6
      content: [
7
        {
8
          type: 'text',
9
          text: 'Please describe the image.',
10
        },
11
        {
12
          type: 'image',
13
          image: fs.readFileSync('./data/image.png'),
14
        },
15
      ],
16
    },
17
  ],
18
});

The model will have access to the image and will respond to questions about it. The image should be passed using the image field.

You can also pass a file-id from the OpenAI Files API.

1
{
2
  type: 'image',
3
  image: 'file-8EFBcWHsQxZV7YGezBC1fq'
4
}

You can also pass the URL of an image.

1
{
2
  type: 'image',
3
  image: 'https://sample.edu/image.png',
4
}

PDF Inputs

The OpenAI Responses API supports reading PDF files. You can pass PDF files as part of the message content using the file type:

1
const result = await generateText({
2
  model: openai('gpt-5'),
3
  messages: [
4
    {
5
      role: 'user',
6
      content: [
7
        {
8
          type: 'text',
9
          text: 'What is an embedding model?',
10
        },
11
        {
12
          type: 'file',
13
          data: fs.readFileSync('./data/ai.pdf'),
14
          mediaType: 'application/pdf',
15
          filename: 'ai.pdf', // optional
16
        },
17
      ],
18
    },
19
  ],
20
});

You can also pass a file-id from the OpenAI Files API.

1
{
2
  type: 'file',
3
  data: 'file-8EFBcWHsQxZV7YGezBC1fq',
4
  mediaType: 'application/pdf',
5
}

You can also pass the URL of a pdf.

1
{
2
  type: 'file',
3
  data: 'https://sample.edu/example.pdf',
4
  mediaType: 'application/pdf',
5
  filename: 'ai.pdf', // optional
6
}

The model will have access to the contents of the PDF file and respond to questions about it. The PDF file should be passed using the data field, and the mediaType should be set to 'application/pdf'.

Structured Outputs

The OpenAI Responses API supports structured outputs. You can enforce structured outputs using generateObject or streamObject, which expose a schema option. Additionally, you can pass a Zod or JSON Schema object to the experimental_output option when using generateText or streamText.

1
// Using generateObject
2
const result = await generateObject({
3
  model: openai('gpt-4.1'),
4
  schema: z.object({
5
    recipe: z.object({
6
      name: z.string(),
7
      ingredients: z.array(
8
        z.object({
9
          name: z.string(),
10
          amount: z.string(),
11
        }),
12
      ),
13
      steps: z.array(z.string()),
14
    }),
15
  }),
16
  prompt: 'Generate a lasagna recipe.',
17
});
18

19
// Using generateText
20
const result = await generateText({
21
  model: openai('gpt-4.1'),
22
  prompt: 'How do I make a pizza?',
23
  experimental_output: Output.object({
24
    schema: z.object({
25
      ingredients: z.array(z.string()),
26
      steps: z.array(z.string()),
27
    }),
28
  }),
29
});

Chat Models

You can create models that call the OpenAI chat API 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.

1
const model = openai.chat('gpt-5');

OpenAI chat models support also some model specific provider options that are not part of the standard call settings. You can pass them in the providerOptions argument:

1
import { openai, type OpenAIChatLanguageModelOptions } from '@ai-sdk/openai';
2

3
const model = openai.chat('gpt-5');
4

5
await generateText({
6
  model,
7
  providerOptions: {
8
    openai: {
9
      logitBias: {
10
        // optional likelihood for specific tokens
11
        '50256': -100,
12
      },
13
      user: 'test-user', // optional unique user identifier
14
    } satisfies OpenAIChatLanguageModelOptions,
15
  },
16
});

The following optional provider options are available for OpenAI chat models:

• logitBias Record<number, number>

  Modifies the likelihood of specified tokens appearing in the completion.

  Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.

  As an example, you can pass {"50256": -100} to prevent the token from being generated.

• logprobs boolean | number

  Return the log probabilities of the tokens. Including logprobs will increase the response size and can slow down response times. However, it can be useful to better understand how the model is behaving.

  Setting to true will return the log probabilities of the tokens that were generated.

  Setting to a number will return the log probabilities of the top n tokens that were generated.

• parallelToolCalls boolean

  Whether to enable parallel function calling during tool use. Defaults to true.

• user string

  A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

• reasoningEffort 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'

  Reasoning effort for reasoning models. Defaults to medium. If you use providerOptions to set the reasoningEffort option, this model setting will be ignored.

  Supported reasoning efforts vary by model. GPT-5.6 supports 'none', 'low', 'medium', 'high', 'xhigh', and 'max'.

• structuredOutputs boolean

  Whether to use structured outputs. Defaults to true.

  When enabled, tool calls and object generation will be strict and follow the provided schema.

• maxCompletionTokens number

  Maximum number of completion tokens to generate. Useful for reasoning models.

• store boolean

  Whether to enable persistence in Responses API.

• metadata Record<string, string>

  Metadata to associate with the request.

• prediction Record<string, any>

  Parameters for prediction mode.

• serviceTier 'auto' | 'flex' | 'priority' | 'default'

  Service tier for the request. Set to 'flex' for 50% cheaper processing at the cost of increased latency (available for o3, o4-mini, and gpt-5 models). Set to 'priority' for faster processing with Enterprise access (available for gpt-4, gpt-5, gpt-5-mini, o3, o4-mini; gpt-5-nano is not supported).

  Defaults to 'auto'.

• strictJsonSchema boolean

  Whether to use strict JSON schema validation. Defaults to false.

• textVerbosity 'low' | 'medium' | 'high'

  Controls the verbosity of the model's responses. Lower values will result in more concise responses, while higher values will result in more verbose responses.

• promptCacheKey string

  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.

• 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.

• safetyIdentifier string

  A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies. The IDs should be a string that uniquely identifies each user.

Reasoning

OpenAI has introduced the o1,o3, and o4 series of reasoning models. Currently, o4-mini, o3, o3-mini, and o1 are available via both the chat and responses APIs. The models codex-mini-latest and computer-use-preview are available only via the responses API.

Reasoning models currently only generate text, have several limitations, and are only supported using generateText and streamText.

They support additional settings and response metadata:

• You can use providerOptions to set

  • the reasoningEffort option (or alternatively the reasoningEffort model setting), which determines the amount of reasoning the model performs.

• You can use response usage.reasoningTokens to access the number of reasoning tokens that the model generated.

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const { text, usage } = await generateText({
5
  model: openai.chat('gpt-5'),
6
  prompt: 'Invent a new holiday and describe its traditions.',
7
  providerOptions: {
8
    openai: {
9
      reasoningEffort: 'low',
10
    },
11
  },
12
});
13

14
console.log(text);
15
console.log('Usage:', {
16
  ...usage,
17
  reasoningTokens: usage.reasoningTokens,
18
});

Structured Outputs

Structured outputs are enabled by default. You can disable them by setting the structuredOutputs option to false.

1
import { openai } from '@ai-sdk/openai';
2
import { generateObject } from 'ai';
3
import { z } from 'zod';
4

5
const result = await generateObject({
6
  model: openai.chat('gpt-4o-2024-08-06'),
7
  providerOptions: {
8
    openai: {
9
      structuredOutputs: false,
10
    },
11
  },
12
  schemaName: 'recipe',
13
  schemaDescription: 'A recipe for lasagna.',
14
  schema: z.object({
15
    name: z.string(),
16
    ingredients: z.array(
17
      z.object({
18
        name: z.string(),
19
        amount: z.string(),
20
      }),
21
    ),
22
    steps: z.array(z.string()),
23
  }),
24
  prompt: 'Generate a lasagna recipe.',
25
});
26

27
console.log(JSON.stringify(result.object, null, 2));

Logprobs

OpenAI provides logprobs information for completion/chat models. You can access it in the providerMetadata object.

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const result = await generateText({
5
  model: openai.chat('gpt-5'),
6
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
7
  providerOptions: {
8
    openai: {
9
      // this can also be a number,
10
      // refer to logprobs provider options section for more
11
      logprobs: true,
12
    },
13
  },
14
});
15

16
const openaiMetadata = (await result.providerMetadata)?.openai;
17

18
const logprobs = openaiMetadata?.logprobs;

Image Support

The OpenAI Chat API supports Image inputs for appropriate models. You can pass Image files as part of the message content using the 'image' type:

1
const result = await generateText({
2
  model: openai.chat('gpt-5'),
3
  messages: [
4
    {
5
      role: 'user',
6
      content: [
7
        {
8
          type: 'text',
9
          text: 'Please describe the image.',
10
        },
11
        {
12
          type: 'image',
13
          image: fs.readFileSync('./data/image.png'),
14
        },
15
      ],
16
    },
17
  ],
18
});

The model will have access to the image and will respond to questions about it. The image should be passed using the image field.

You can also pass the URL of an image.

1
{
2
  type: 'image',
3
  image: 'https://sample.edu/image.png',
4
}

PDF support

The OpenAI Chat API supports reading PDF files. You can pass PDF files as part of the message content using the file type:

1
const result = await generateText({
2
  model: openai.chat('gpt-5'),
3
  messages: [
4
    {
5
      role: 'user',
6
      content: [
7
        {
8
          type: 'text',
9
          text: 'What is an embedding model?',
10
        },
11
        {
12
          type: 'file',
13
          data: fs.readFileSync('./data/ai.pdf'),
14
          mediaType: 'application/pdf',
15
          filename: 'ai.pdf', // optional
16
        },
17
      ],
18
    },
19
  ],
20
});

The model will have access to the contents of the PDF file and respond to questions about it. The PDF file should be passed using the data field, and the mediaType should be set to 'application/pdf'.

You can also pass a file-id from the OpenAI Files API.

1
{
2
  type: 'file',
3
  data: 'file-8EFBcWHsQxZV7YGezBC1fq',
4
  mediaType: 'application/pdf',
5
}

You can also pass the URL of a PDF.

1
{
2
  type: 'file',
3
  data: 'https://sample.edu/example.pdf',
4
  mediaType: 'application/pdf',
5
  filename: 'ai.pdf', // optional
6
}

Predicted Outputs

OpenAI supports predicted outputs for gpt-4o and gpt-4o-mini. Predicted outputs help you reduce latency by allowing you to specify a base text that the model should modify. You can enable predicted outputs by adding the prediction option to the providerOptions.openai object:

1
const result = streamText({
2
  model: openai.chat('gpt-5'),
3
  messages: [
4
    {
5
      role: 'user',
6
      content: 'Replace the Username property with an Email property.',
7
    },
8
    {
9
      role: 'user',
10
      content: existingCode,
11
    },
12
  ],
13
  providerOptions: {
14
    openai: {
15
      prediction: {
16
        type: 'content',
17
        content: existingCode,
18
      },
19
    },
20
  },
21
});

OpenAI provides usage information for predicted outputs (acceptedPredictionTokens and rejectedPredictionTokens). You can access it in the providerMetadata object.

1
const openaiMetadata = (await result.providerMetadata)?.openai;
2

3
const acceptedPredictionTokens = openaiMetadata?.acceptedPredictionTokens;
4
const rejectedPredictionTokens = openaiMetadata?.rejectedPredictionTokens;

Image Detail

You can use the openai provider option to set the image input detail to high, low, original, or auto:

1
const result = await generateText({
2
  model: openai.chat('gpt-5'),
3
  messages: [
4
    {
5
      role: 'user',
6
      content: [
7
        { type: 'text', text: 'Describe the image in detail.' },
8
        {
9
          type: 'image',
10
          image:
11
            'https://github.com/vercel/ai/blob/main/examples/ai-core/data/comic-cat.png?raw=true',
12

13
          // OpenAI specific options - image detail:
14
          providerOptions: {
15
            openai: { imageDetail: 'low' },
16
          },
17
        },
18
      ],
19
    },
20
  ],
21
});

For GPT-5.6, original preserves the input dimensions without resizing to a patch budget or pixel-dimension limit. auto and an omitted detail setting use the same sizing behavior as original, which can increase input token usage for large images.

Distillation

OpenAI supports model distillation for some models. If you want to store a generation for use in the distillation process, you can add the store option to the providerOptions.openai object. This will save the generation to the OpenAI platform for later use in distillation.

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3
import 'dotenv/config';
4

5
async function main() {
6
  const { text, usage } = await generateText({
7
    model: openai.chat('gpt-4o-mini'),
8
    prompt: 'Who worked on the original macintosh?',
9
    providerOptions: {
10
      openai: {
11
        store: true,
12
        metadata: {
13
          custom: 'value',
14
        },
15
      },
16
    },
17
  });
18

19
  console.log(text);
20
  console.log();
21
  console.log('Usage:', usage);
22
}
23

24
main().catch(console.error);

Prompt Caching

OpenAI has introduced Prompt Caching for supported models including gpt-4o and gpt-4o-mini.

• Prompt caching is automatically enabled for these models, when the prompt is 1024 tokens or longer. It does not need to be explicitly enabled.
• Cache reads are reported in usage.cachedInputTokens.
• For GPT-5.6 and later models, cache writes are reported in providerMetadata.openai.usage.cacheWriteTokens.
• 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.

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const { text, usage } = await generateText({
5
  model: openai.chat('gpt-4o-mini'),
6
  prompt: 'A 1024-token or longer prompt...',
7
});
8

9
console.log('Cache reads:', usage.cachedInputTokens);

To improve cache hit rates, you can manually control caching using the promptCacheKey option:

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const { usage } = await generateText({
5
  model: openai.chat('gpt-5'),
6
  prompt: 'A 1024-token or longer prompt...',
7
  providerOptions: {
8
    openai: {
9
      promptCacheKey: 'my-custom-cache-key-123',
10
    },
11
  },
12
});
13

14
console.log('Cache reads:', usage.cachedInputTokens);

GPT-5.6 and later models support explicit cache breakpoints on system messages and supported text, image, and file content blocks. Set a request-level cache key and mark the end of each reusable prefix with promptCacheBreakpoint:

1
import {
2
  openai,
3
  type OpenAIResponsesProviderOptions,
4
} from '@ai-sdk/openai';
5
import { generateText } from 'ai';
6

7
const { text, usage, providerMetadata } = await generateText({
8
  model: openai.responses('gpt-5.6'),
9
  providerOptions: {
10
    openai: {
11
      promptCacheKey: 'tenant:acme:support-v1',
12
      promptCacheOptions: { mode: 'explicit', ttl: '30m' },
13
    } satisfies OpenAIResponsesProviderOptions,
14
  },
15
  messages: [
16
    {
17
      role: 'user',
18
      content: [
19
        {
20
          type: 'text',
21
          text: 'A stable prefix of at least 1024 tokens...',
22
          providerOptions: {
23
            openai: {
24
              promptCacheBreakpoint: { mode: 'explicit' },
25
            },
26
          },
27
        },
28
        { type: 'text', text: 'What should I do next?' },
29
      ],
30
    },
31
  ],
32
});
33

34
const openaiMetadata = providerMetadata?.openai as
35
  | { usage?: { cacheWriteTokens?: number } }
36
  | undefined;
37
console.log('Cache reads:', usage.cachedInputTokens);
38
console.log('Cache writes:', openaiMetadata?.usage?.cacheWriteTokens);

In 'implicit' mode, OpenAI places an automatic breakpoint on the latest message and also honors explicit breakpoints. In 'explicit' mode, only marked content blocks are eligible for caching; a request without any explicit breakpoint does not use prompt caching.

In AI SDK v5, a breakpoint on a tool-result part applies to the whole tool result. When the result contains multiple nested output parts, the OpenAI provider places the API breakpoint on the final nested part because the v5 provider interface does not carry provider options on each nested output item.

For models before GPT-5.6 that support extended caching, you can keep cached prefixes active for up to 24 hours:

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const { usage } = await generateText({
5
  model: openai.chat('gpt-5.1'),
6
  prompt: 'A 1024-token or longer prompt...',
7
  providerOptions: {
8
    openai: {
9
      promptCacheKey: 'my-custom-cache-key-123',
10
      promptCacheRetention: '24h',
11
    },
12
  },
13
});
14

15
console.log('Cache reads:', usage.cachedInputTokens);

Audio Input

With the gpt-4o-audio-preview model, you can pass audio files to the model.

1
import { openai } from '@ai-sdk/openai';
2
import { generateText } from 'ai';
3

4
const result = await generateText({
5
  model: openai.chat('gpt-4o-audio-preview'),
6
  messages: [
7
    {
8
      role: 'user',
9
      content: [
10
        { type: 'text', text: 'What is the audio saying?' },
11
        {
12
          type: 'file',
13
          mediaType: 'audio/mpeg',
14
          data: fs.readFileSync('./data/galileo.mp3'),
15
        },
16
      ],
17
    },
18
  ],
19
});

Completion Models

You can create models that call the OpenAI completions API using the .completion() factory method. The first argument is the model id. Currently only gpt-3.5-turbo-instruct is supported.

1
const model = openai.completion('gpt-3.5-turbo-instruct');

OpenAI completion models support also some model specific settings that are not part of the standard call settings. You can pass them as an options argument:

1
const model = openai.completion('gpt-3.5-turbo-instruct');
2

3
await model.doGenerate({
4
  providerOptions: {
5
    openai: {
6
      echo: true, // optional, echo the prompt in addition to the completion
7
      logitBias: {
8
        // optional likelihood for specific tokens
9
        '50256': -100,
10
      },
11
      suffix: 'some text', // optional suffix that comes after a completion of inserted text
12
      user: 'test-user', // optional unique user identifier
13
    },
14
  },
15
});

The following optional provider options are available for OpenAI completion models:

• echo: boolean

  Echo back the prompt in addition to the completion.

• logitBias Record<number, number>

  Modifies the likelihood of specified tokens appearing in the completion.

  Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.

  As an example, you can pass {"50256": -100} to prevent the <|endoftext|> token from being generated.

• logprobs boolean | number

  Return the log probabilities of the tokens. Including logprobs will increase the response size and can slow down response times. However, it can be useful to better understand how the model is behaving.

  Setting to true will return the log probabilities of the tokens that were generated.

  Setting to a number will return the log probabilities of the top n tokens that were generated.

• suffix string

  The suffix that comes after a completion of inserted text.

• user string

  A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Model Capabilities