OpenAI language model provider options for Responses API
Responses models accept provider options via OpenAILanguageModelResponsesOptions type with the following properties: parallelToolCalls (boolean, defaults to true), store (boolean, defaults to true), passThroughUnsupportedFiles (boolean, defaults to false), maxToolCalls (integer), metadata (Record<string, string>), conversation (string), previousResponseId (string), instructions (string), logprobs (boolean | number, 1-20), user (string), reasoningEffort ('none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', defaults to 'medium'), reasoningMode ('standard' | 'pro'), reasoningContext ('auto' | 'current_turn' | 'all_turns'), reasoningSummary ('auto' | 'detailed'), strictJsonSchema (boolean, defaults to true), serviceTier ('auto' | 'flex' | 'priority' | 'fast' | 'default', defaults to 'auto'), textVerbosity ('low' | 'medium' | 'high', defaults to 'medium'), include (Array<string>), truncation (string with 'auto' or 'disabled' default), promptCacheKey (string), promptCacheOptions (object with mode 'implicit'|'explicit' and ttl '30m'), promptCacheRetention ('in_memory' | '24h'), safetyIdentifier (string), systemMessageMode ('system' | 'developer' | 'remove'), forceReasoning (boolean), contextManagement (Array<object> with type 'compaction' and compactThreshold number).
OpenAI Responses API provider metadata
The Responses API returns provider-specific metadata including responseId (string | null | undefined, can be used to continue a conversation), logprobs (optional, log probabilities of output tokens when enabled), serviceTier (optional, service tier information returned by the API), reasoningContext (optional, effective persisted-reasoning context for GPT-5.6, values 'current_turn' or 'all_turns').
OpenAI reasoning effort support by model
Supported reasoning efforts vary by model. GPT-5.6 supports 'none', 'low', 'medium', 'high', 'xhigh', and 'max'.
OpenAI service tier options and availability
Service tier options are 'auto' (default), 'flex' (50% cheaper, increased latency, available for o3, o4-mini, gpt-5), 'priority' (faster processing with Enterprise access, available for gpt-4, gpt-5, gpt-5-mini, o3, o4-mini; not for gpt-5-nano), and 'fast' (OpenAI's newer name for 'priority', interchangeable, gpt-5.6 and earlier report 'priority').
OpenAI reasoning models and defaults
When reasoningEffort is set to a value other than 'none', the OpenAI Responses provider defaults reasoningSummary to 'detailed'. Set reasoningSummary: null to omit reasoning summaries.
OpenAI WebSocket transport for Responses API
The ai-sdk-openai-websocket-fetch package provides a drop-in fetch replacement that routes streaming requests through a persistent WebSocket connection to the OpenAI Responses API. The first request establishes the WebSocket connection (slower), but subsequent requests reuse the open connection, reducing TTFB. Non-streaming requests fall through to standard fetch. Pass the WebSocket fetch to createOpenAI via the fetch option.
OpenAI textVerbosity parameter effect
The textVerbosity parameter ('low', 'medium', 'high') scales output length without changing the underlying prompt. 'low' produces terse minimal responses, 'medium' is balanced detail (default), 'high' produces verbose responses with comprehensive detail.
OpenAI image input file types
The OpenAI Responses API supports Image inputs. Pass Image files using type 'file' with mediaType 'image' and data as raw bytes, file-id from OpenAI Files API, or URL string.
OpenAI PDF input support
The OpenAI Responses API supports PDF files passed with type 'file', mediaType 'application/pdf', data as raw bytes/file-id/URL, and optional filename. The model has access to PDF contents and can respond to questions about it.
OpenAI reasoning output in streaming
When reasoningSummary is enabled in streamText, reasoning summaries appear as stream events with type 'reasoning'. When reasoningEffort is set to non-'none', provider defaults reasoningSummary to 'detailed'.
OpenAI reasoning output in non-streaming
For non-streaming calls with generateText and reasoningSummary enabled, reasoning summaries are available in the reasoning field of the response.
OpenAI text provider metadata with annotations
When using Responses API with generateText/streamText, text parts include OpenaiResponsesTextProviderMetadata via providerMetadata with itemId (string) and annotations (optional array). Annotations are discriminated unions with type field including url_citation, file_citation, container_file_citation, file_path.
OpenAI reasoning provider metadata
Reasoning parts include OpenaiResponsesReasoningProviderMetadata with itemId (string) and reasoningEncryptedContent (optional, only when requested via include: ['reasoning.encrypted_content']).
OpenAI source document provider metadata
Source document parts (part.type === 'source', sourceType === 'document') include OpenaiResponsesSourceDocumentProviderMetadata as discriminated union with type field (file_citation, container_file_citation, file_path), each including fileId and containerId identifiers.
OpenAI truncation strategy
The truncation strategy ('auto' or 'disabled', default is 'disabled') controls response truncation. 'auto' truncates response to fit context window by dropping conversation items from beginning. 'disabled' fails with 400 error if input exceeds context window.
OpenAI prompt caching configuration
Prompt caching can be configured with promptCacheKey (string for manual control), promptCacheOptions (object with mode 'implicit'|'explicit' and ttl '30m' for GPT-5.6+), and promptCacheRetention ('in_memory'|'24h' for legacy models before GPT-5.6).
OpenAI system message mode control
The systemMessageMode parameter ('system'|'developer'|'remove') controls the role of the system message. By default, for reasoning models the system message is converted to developer message. 'system' passes as system-level instruction, 'developer' as developer message, 'remove' omits system message.
OpenAI context management for compaction
The contextManagement parameter is an array of objects with type 'compaction' and compactThreshold (number) token count to trigger server-side context compression when token usage crosses the threshold.
OpenAI generateText with reasoning example
Example: await generateText({ model: openai('gpt-5'), prompt: 'Tell me about the Mission burrito debate in San Francisco.', providerOptions: { openai: { reasoningSummary: 'auto' } } }). Results include reasoning field with summaries.
OpenAI streamText with reasoning example
Example: streamText({ model: openai('gpt-5'), prompt: 'Tell me about the Mission burrito debate in San Francisco.', providerOptions: { openai: { reasoningSummary: 'detailed' } } }). Stream parts include type 'reasoning' with textDelta and type 'text-delta' for response text.
OpenAI generateText with textVerbosity example
Example: await generateText({ model: openai('gpt-5-mini'), prompt: 'Write a poem about a boy and his first pet dog.', providerOptions: { openai: { textVerbosity: 'low' } } }). Use 'low', 'medium' (default), or 'high'.
OpenAI strict structured outputs configuration
Strict structured outputs are enabled by default for OpenAI chat models. Set strictJsonSchema option to false to disable. Note: Optional schema properties are not supported; change Zod .nullish() and .optional() to .nullable().
OpenAI image input example
Example: generateText({ model: openai('gpt-5'), messages: [{ role: 'user', content: [{ type: 'text', text: 'Please describe the image.' }, { type: 'file', mediaType: 'image', data: readFileSync('./data/image.png') }] }] }). Can also use file-id string or URL string.
OpenAI PDF input example
Example: generateText({ model: openai('gpt-5'), messages: [{ role: 'user', content: [{ type: 'text', text: 'What is an embedding model?' }, { type: 'file', data: readFileSync('./data/ai.pdf'), mediaType: 'application/pdf', filename: 'ai.pdf' }] }] }). Can also use file-id or URL.
OpenAI structured outputs example
Example: generateText({ model: openai('gpt-4.1'), output: Output.object({ schema: z.object({ recipe: z.object({ name: z.string(), ingredients: z.array(z.object({ name: z.string(), amount: z.string() })), steps: z.array(z.string()) }) }) }), prompt: 'Generate a lasagna recipe.' }).
OpenAI WebSocket fetch example
Example: const wsFetch = createWebSocketFetch(); const openai = createOpenAI({ fetch: wsFetch }); const result = streamText({ model: openai('gpt-4.1-mini'), prompt: 'Hello!', tools: { /* ... */ }, onFinish: () => wsFetch.close() }).
OpenAI basic generateText example
Example: const { text } = await generateText({ model: openai('gpt-5'), prompt: 'Write a vegetarian lasagna recipe for 4 people.' }).
OpenAI temperature and sampling parameters
The OpenAI provider documentation does not explicitly list temperature or other sampling parameters in the Responses API options. Refer to OpenAI API documentation for supported sampling parameters.
OpenAI token output limit control
The OpenAI provider documentation for Responses API does not explicitly mention a parameter to control token output limits (like maxTokens). Refer to OpenAI API documentation for output limit parameters.
OpenAI temperature parameter for transcription
OpenAI transcription models accept a temperature provider option with values between 0 and 1. Higher values like 0.8 make output more random, while lower values like 0.2 make it more focused and deterministic. If set to 0, the model uses log probability to automatically increase the temperature until certain thresholds are hit. Defaults to 0.
OpenAI sampling parameter: logprobs
OpenAI chat and completion models support logprobs provider option which can be either a boolean or a number. Setting to true returns log probabilities of generated tokens. Setting to a number returns log probabilities of the top n tokens. You can access it via providerMetadata.openai.logprobs.
OpenAI token output limits via maxCompletionTokens
OpenAI chat models accept maxCompletionTokens provider option to control maximum number of completion tokens to generate. This is useful for reasoning models. For reasoning models, maxOutputTokens is automatically mapped to max_completion_tokens.
OpenAI chat model provider options reference
OpenAI chat models support the following optional provider options in providerOptions.openai:
- logitBias (Record<number, number>): Modifies likelihood of specified tokens appearing, accepts bias values from -100 to 100
- logprobs (boolean | number): Returns log probabilities, true for all tokens or number for top n
- parallelToolCalls (boolean): Enable parallel function calling, defaults to true
- user (string): Unique end-user identifier for abuse detection
- reasoningEffort ('none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'): For reasoning models, defaults to medium
- maxCompletionTokens (number): Maximum completion tokens to generate
- store (boolean): Enable persistence in Responses API
- metadata (Record<string, string>): Metadata to associate with request
- prediction (Record<string, any>): Parameters for prediction mode
- serviceTier ('auto' | 'flex' | 'priority' | 'fast' | 'default'): auto is default, flex for 50% cheaper with increased latency, priority/fast for faster processing
- strictJsonSchema (boolean): Use strict JSON schema validation, defaults to true
- textVerbosity ('low' | 'medium' | 'high'): Controls response verbosity
- promptCacheKey (string): Cache key for manual prompt caching
- promptCacheOptions (object): Configures prompt caching with mode ('implicit' or 'explicit') and ttl (currently '30m')
- promptCacheRetention ('in_memory' | '24h'): Legacy retention policy for models before GPT-5.6
- safetyIdentifier (string): Stable identifier to detect users violating usage policies
- systemMessageMode ('system' | 'developer' | 'remove'): Override system message mode
- forceReasoning (boolean): Force treating model as reasoning model for unknown model IDs
- imageDetail ('high' | 'low' | 'original' | 'auto'): Set image input detail level for vision models
OpenAI completion model provider options reference
OpenAI completion models support the following optional provider options in providerOptions.openai:
- echo (boolean): Echo back the prompt in addition to completion
- logitBias (Record<number, number>): Modifies likelihood of specified tokens, accepts bias values from -100 to 100
- logprobs (boolean | number): Return log probabilities, true for all tokens or number for top n
- suffix (string): Suffix that comes after completion of inserted text
- user (string): Unique end-user identifier for abuse detection
OpenAI embedding model provider options reference
OpenAI embedding models support the following optional provider options in providerOptions.openai:
- dimensions (number): The number of dimensions the resulting output embeddings should have, only supported in text-embedding-3 and later models
- user (string): Unique end-user identifier for abuse detection
OpenAI image model provider options reference
OpenAI image models support optional providerOptions that are model-dependent. gpt-image-* models support quality option ('high', 'medium', or 'low'). Image editing options include background ('transparent' or 'opaque') and outputFormat ('png', 'webp', or 'jpeg').
OpenAI transcription model provider options reference
OpenAI transcription models support the following provider options in providerOptions.openai:
- timestampGranularities (string[]): Granularity of timestamps, defaults to ['segment'], possible values are ['word'], ['segment'], and ['word', 'segment']. Word timestamps incur additional latency
- language (string): Input audio language in ISO-639-1 format (e.g. 'en') improves accuracy and latency, optional
- prompt (string): Optional text to guide model style or continue previous segment, should match audio language
- temperature (number): Sampling temperature between 0 and 1, defaults to 0
- include (string[]): Additional information to include in response
- streaming (object): Options for streaming models like gpt-realtime-whisper with delay ('minimal' | 'low' | 'medium' | 'high' | 'xhigh') and include (string[])
OpenAI responses API compaction metadata fields
OpenAI Responses API compaction items include the following metadata fields:
- type (always 'compaction')
- itemId (string): The ID of the compaction item in the Responses API
- encryptedContent (string, optional): The encrypted compaction state automatically sent back to API in subsequent requests
OpenAI image detail levels for vision models
OpenAI vision models support imageDetail provider option with values: 'high', 'low', 'original', or 'auto'. For GPT-5.6, 'original' preserves input dimensions without resizing; 'auto' and omitted detail setting behave like 'original' and can increase input token usage for large images.
OpenAI predicted outputs for latency optimization
OpenAI supports predicted outputs for gpt-4o and gpt-4o-mini to reduce latency. Enable by adding prediction option to providerOptions.openai with type: 'content' and content: baseText. Usage info includes acceptedPredictionTokens and rejectedPredictionTokens accessible via providerMetadata.openai.
OpenAI prompt caching automatic enablement
Prompt caching is automatically enabled for supported models like gpt-4o and gpt-4o-mini when the prompt is 1024 tokens or longer. Access cached tokens via usage.inputTokenDetails.cacheReadTokens. For GPT-5.6+, usage.inputTokenDetails.cacheWriteTokens reports tokens written to cache.
OpenAI explicit prompt cache breakpoints for GPT-5.6
GPT-5.6 and later models support explicit cache breakpoints on text, image, and file content blocks. Set request-level promptCacheKey and promptCacheOptions with mode: 'explicit' and ttl: '30m'. Mark end of reusable prefix with providerOptions.openai.promptCacheBreakpoint: { mode: 'explicit' }. In explicit mode, only marked content blocks are eligible for caching.
OpenAI prompt cache retention for models before GPT-5.6
For models before GPT-5.6 that support extended caching, use promptCacheRetention option set to '24h' to keep cached prefixes active for up to 24 hours.
OpenAI distillation store option
OpenAI supports model distillation. Use the store option in providerOptions.openai set to true to save the generation to OpenAI platform for later use in distillation process. Can include metadata via metadata option.
OpenAI systemMessageMode configuration example
Example of controlling system message handling in reasoning models:
```ts
const result = await generateText({
model: openai.chat('gpt-5'),
messages: [
{ role: 'system', content: 'You are a helpful assistant.' },
{ role: 'user', content: 'Tell me a joke.' },
],
providerOptions: {
openai: {
systemMessageMode: 'system',
} satisfies OpenAILanguageModelChatOptions,
},
});
```
OpenAI image detail level example
Example of setting image detail level for vision models:
```ts
const result = await generateText({
model: openai.chat('gpt-5'),
messages: [
{
role: 'user',
content: [
{ type: 'text', text: 'Describe the image in detail.' },
{
type: 'file',
mediaType: 'image',
data: 'https://github.com/vercel/ai/blob/main/examples/ai-functions/data/comic-cat.png?raw=true',
providerOptions: {
openai: { imageDetail: 'low' },
},
},
],
},
],
});
```
OpenAI distillation example
Example of storing generation for distillation:
```ts
const { text, usage } = await generateText({
model: openai.chat('gpt-4o-mini'),
prompt: 'Who worked on the original macintosh?',
providerOptions: {
openai: {
store: true,
metadata: {
custom: 'value',
},
} satisfies OpenAILanguageModelChatOptions,
},
});
console.log(text);
console.log('Usage:', usage);
```
OpenAI explicit prompt cache breakpoints example
Example of GPT-5.6 explicit prompt cache breakpoints:
```ts
const { usage } = await generateText({
model: openai('gpt-5.6'),
providerOptions: {
openai: {
promptCacheKey: 'tenant:acme:support-v1',
promptCacheOptions: { mode: 'explicit', ttl: '30m' },
} satisfies OpenAILanguageModelResponsesOptions,
},
messages: [
{
role: 'user',
content: [
{
type: 'text',
text: `A stable prefix of at least 1024 tokens...`,
providerOptions: {
openai: {
promptCacheBreakpoint: { mode: 'explicit' },
},
},
},
{ type: 'text', text: 'What should I do next?' },
],
},
],
});
console.log('Cache reads:', usage.inputTokenDetails.cacheReadTokens);
console.log('Cache writes:', usage.inputTokenDetails.cacheWriteTokens);
```
OpenAI 24-hour prompt cache retention example
Example of extended prompt caching for models before GPT-5.6:
```ts
const { text, usage } = await generateText({
model: openai.chat('gpt-5.5'),
prompt: `A 1024-token or longer prompt...`,
providerOptions: {
openai: {
promptCacheKey: 'my-custom-cache-key-123',
promptCacheRetention: '24h',
} satisfies OpenAILanguageModelChatOptions,
},
});
console.log('Cached tokens:', usage.inputTokenDetails.cacheReadTokens);
```
OpenAI speech generation with options example
Example of generating speech with provider options:
```ts
const result = await generateSpeech({
model: openai.speech('tts-1'),
text: 'Hello, world!',
voice: 'alloy',
providerOptions: {
openai: {
speed: 1.2,
} satisfies OpenAISpeechModelOptions,
},
});
```
OpenAI image generation quality option example
Example of image generation with quality option:
```ts
const { image, providerMetadata } = await generateImage({
model: openai.image('gpt-image-2'),
prompt: 'A salamander at sunrise in a forest pond in the Seychelles.',
providerOptions: {
openai: { quality: 'high' } satisfies OpenAIImageModelGenerationOptions,
},
});
```
OpenAI dall-e models do not support aspectRatio parameter
Dall-E models do not support the aspectRatio parameter. Use the size parameter instead.
OpenAI UIMessage type limitation with providerOptions
The UIMessage type used by AI SDK UI hooks like useChat does not support the providerOptions property. Use convertToModelMessages first before passing messages to functions like generateText or streamText when you need to use providerOptions.
OpenAI predicted outputs have limitations
OpenAI Predicted Outputs have several limitations including unsupported API parameters and no tool calling support.
OpenAI strict structured outputs limitations
OpenAI structured outputs have several limitations around supported schemas. For example, optional schema properties are not supported. Change Zod .nullish() and .optional() to .nullable().
OpenAI prompt caching examples
OpenAI supports prompt caching to reduce token costs on repeated requests.
## Automatic prompt caching
When using a prompt of 1024 tokens or longer, caching is automatic:
```ts
const { text, usage } = await generateText({
model: openai.chat('gpt-4o-mini'),
prompt: `A 1024-token or longer prompt...`,
});
console.log('Cached tokens:', usage.inputTokenDetails.cacheReadTokens);
```
## Manual prompt cache control
To manually control the cache key:
```ts
const { text, usage } = await generateText({
model: openai.chat('gpt-5'),
prompt: `A 1024-token or longer prompt...`,
providerOptions: {
openai: {
promptCacheKey: 'my-custom-cache-key-123',
} satisfies OpenAILanguageModelChatOptions,
},
});
console.log('Cached tokens:', usage.inputTokenDetails.cacheReadTokens);
```
In both cases, check `usage.inputTokenDetails.cacheReadTokens` to see the number of tokens served from cache.
OpenAI speech model provider options
OpenAI speech models support optional provider options via `providerOptions.openai` of type `OpenAISpeechModelOptions`, including:
- **instructions** (string): Additional instructions to control voice behavior, such as 'Speak in a slow and steady tone'. This option does not work with tts-1 or tts-1-hd models.
- **speed** (number): Speed of the generated audio. Accepts values from 0.25 to 4.0, defaults to 1.0.
Both options are optional.