openai

Package

@ai-sdk/openai

Factories

AIProviders.openAI

Capabilities

• Language
• Completion
• Embedding
• Image
• Transcription
• Speech
• Evaluation
• Decision
• Files
• Skills

Decisions and current Responses behavior

Use provider.decisionModel("gpt-6-luna") with AI.experimentalDecide. OpenAI Decisions send /decisions, named questions and inline image evidence; the experimental Evaluation entry points remain available through the same native implementation. Choice, score and boolean questions can omit instructions. Boolean criteria still become predicate instructions. The native Decisions endpoint ignores maxOutputTokens and reasoning, reporting an unsupported warning for each supplied setting.

GPT-6-sol/luna sampling and logprobs follow the final effective reasoning effort, including configuration updates. Typed tool errors are wrapped as { "error": value } in OpenAI requests. Failed/incomplete web-search results keep error/status metadata in generation, streaming and batch results. Stored assistant references retain structured-output schema breakpoints.

Batch downloads accept ProviderSettings.batchResultDownloads with a default 64 MiB UTF-8 row limit.

Citation and history parity

Responses text content exposes citations independently of result.sources; streaming text-end parts carry the same citations. Citation sources use stable URL or file IDs and retain provider UTF-16 offsets. Retrieved web URLs and deduplicated file-search documents populate standalone sources, including uncited retrieved documents. Annotation sources remain a fallback when retrieval data is absent; file_path annotations remain standalone sources only.

For tools loaded during a conversation, attach providerMetadata: ["openai": ["additionalTools": [...]]] to an ordinary AIToolResult. Each strict function definition requires type: "function", a nonempty name, and object parameters, with optional description and strict. The request inserts a developer additional_tools item immediately after that result. Set a function tool’s providerOptions.openai.omitFromRequestTools to true to retain local execution and validation while omitting its top-level definition. Such tools cannot be forced or allow-listed until they are available through history.

Stored reasoning-model assistant text replays its content when the preceding reasoning was pruned. With store: false, provider-executed web-search results replay search/open-page/find-in-page actions. Custom tool streaming declares inputEncoding: .text. webSearchPreview is deprecated; use webSearch.

Prompt cache prewarming and shell controls

Responses accepts providerOptions.openai.promptCacheOptions with mode: "implicit" or "explicit", ttl: "30m" or "12h", and optional prewarm: true. A prewarm response or stream may contain no text and zero output tokens. Cache-write totals remain available in TokenUsage; rawValue.input_tokens_details.cache_write_tokens_details preserves the 30-minute and 12-hour token breakdown. User text parts forward providerMetadata.openai.promptCacheBreakpoint, including ttl: "12h" with mode: "explicit", to the corresponding input content entry.

Shell calls are marked providerExecuted for container environments and remain client calls for local execution. Shell tool-call input preserves action.timeoutMs and action.maxOutputLength when OpenAI supplies them. Shell results expose maxOutputLength; replaying assistant history with store: false or sending a tool result keeps that output limit. Null controls are omitted in generated and streamed tool input/results.

Transcription languages

Transcription normalizes recognized English language names and lowercase two-letter codes. When language is absent or unrecognized, exactly one valid entry in the returned languages list supplies result.language; mixed-language responses leave it unset. providerMetadata.openai.languages preserves the detected list, including an empty list, alongside diarized segments. Unknown language names and locale strings such as en-US no longer appear as normalized language codes.

Final-answer JSON and incomplete streams

For JSON Responses, the last message marked final_answer is exposed as TextGenerationResult.structuredOutputText for structured parsing. Full text, content, citations and message metadata still include draft messages. A missing selection uses concatenated text; an empty selection stays explicit. Ordinary text requests retain their existing full-content behavior.

Chat, Completion and Responses streams that end without a provider completion signal finish as interrupted. Preserve the partial output and choose whether to retry; tool execution and automatic continuation stop for that response.

Notes

OpenAI mirrors upstream 4.0.102 across Chat Completions, Responses language models, completions, embeddings, images, speech, transcription, files, skills, hosted Responses tools, provider tool helpers, organization/project headers, structured output, usage details, response/provider metadata, warnings, raw stream chunks, provider references, Responses allowedTools for built-in and provider-defined tools with validated allow-list mappings and warnings, tool-search/namespace handling including blocked-domain filters, server-side compaction items, retryable pre-output stream failures, and Chat file-part mapping for image/audio/PDF inputs. File uploads serialize expiry options as nested expires_after[anchor] and expires_after[seconds] multipart fields; Chat metadata ignores zero-valued Azure content-filter placeholder timestamps while generic compatible providers preserve explicit epoch timestamps. The latest pass JSON-encodes function outputs that declare output schemas, keeps streaming output-item identity stable across rotating IDs through output_index, supports serviceTier: fast, and adds Responses programmatic tool calling with caller controls, output schemas, streamed/generated program items, and multi-step continuation; preserves stored tool-search IDs; and applies reasoning, sampling, service-tier, and image defaults to recognizable future OpenAI model versions. The current pass also adds terminal compaction triggers, previous-response function/output pairing, storage-disabled shell replay, MCP approval reference deduplication, distinct openai.computer actions/safety-check parsing and screenshot replay, plus durable Responses Batch V4 file upload, status, and streamed result conversion. Chat reasoning models strip unsupported sampling and penalty fields with upstream warnings, while topLogprobs is always omitted even when GPT-5.1+ permits non-reasoning parameters at effort none. The 4.0.52 pass also adds Batch webhook warnings and reconciled results/counts, embedding byte budgets, typed and schema-invalid stream failures, non-object tool-argument replay, function-name-aware tool-search history, scalar cache breakpoints, and safe identifier encoding. Browser WebRTC, ProviderV4 type names, ESM-only packaging, Node 22 engines, and workflow serialization helpers remain JS-runtime/package-surface concerns. The 4.0.60 pass adds GPT-6 and reasoningEffortUpdate, image-generation actions, diarized transcription and chunking, complete Files V4 metadata/download/delete and streaming upload operations, and Batch tool content plus input-file and expiry provider metadata. The 2026-09-20 pass adds the Evaluation V4 adapter, current Responses assistant/reference conversion and media abort handling, plus the portable server-WebSocket OpenAI Live adapter over continuous realtime sessions; browser WebRTC remains deferred. The 2026-09-27 pass makes audio transcripts a fallback for nil or empty chat content, supports GPT-6 Sol and Luna none reasoning updates with positioned validation and deduplication, defaults function tools to strict false, and removes unsupported regex lookarounds recursively. The 2026-10-04 pass expands recursive singleton allOf references while preserving true intersections, reports image file/mask capabilities, and preserves transcription billing usage. The 2026-10-11 pass: Decision V4 uses native /decisions with image evidence and refusals. GPT-6-sol/luna reasoning gates, failed web-search results, stored assistant IDs, typed OpenAI error codes and line-bounded batch downloads follow published behavior. The 2026-10-18 pass: Attached citations are separate from retrieved URL/document sources. History-loaded additionalTools, omitted top-level function definitions, pruned-reasoning replay and storage-disabled web-search replay are supported. Custom-tool deltas declare text encoding and final string inputs remain JSON encoded. webSearchPreview is deprecated. The 2026-10-23 pass: Responses supports 12h cache TTL, prewarm, nested cache-write token metadata and shell timeout/max-output fields; transcription normalizes language and retains metadata. Decision omits absent Choice/Score instructions and reports unsupported shared controls. The 2026-10-25 pass: JSON Responses select the last final_answer through structuredOutputText while retaining drafts and all content. Chat, Completion and Responses cutoffs report interrupted.

Factory argument requirements are defined by the public Swift factory signatures. Use Public symbols when you need the exact initializer or factory declaration.

Return to the provider matrix.