# What changed in @ai-sdk/provider

> 83 changes in @ai-sdk/provider 2 to 4 from its official release notes, upgrade guides and advisories: 20 breaking, 1 deprecations, 2 security, 37 new APIs and options. Each one cited. Sources checked 2026-11-12. HTML: https://unstale.sh/npm/@ai-sdk/provider/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @ai-sdk/provider 4

### Breaking changes

- Adds a typed streaming heartbeat part. Consumers with exhaustive stream-part switches must handle the new union variant, even when the opt-in is disabled. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- mediaType can be undefined when a provider fetches an audio URL natively, so telemetry integrations should check for missing values before using it as a string. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Arrays passed directly as state are interpreted as decision state parts; wrap JSON arrays in an object or a json part. (4.0.25) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.25)
- Decision refusals are reported as refusal answers, changing how providers represent refusals. (4.0.24) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.24)
- Renames evaluate to decide. (4.0.22) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.22)

### Security

- Optional request metadata and model-call end events report the actual OpenAI Chat HTTP endpoint; generation results, callbacks, and OpenTelemetry spans expose only sanitized endpoint information. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- @ai-sdk/provider-utils has an Uncontrolled Resource Consumption issue (4.0.33) — [security advisory](https://github.com/advisories/GHSA-866G-F22W-33X8)

### Deprecations

- Portable minimal and xhigh retain their low and high mappings and now return compatibility warnings; max maps to high with the same warning behavior in generation and streaming results. (4.0.23) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.23)

### New APIs and options

- Provider metadata now exposes structured Score legends. (4.0.37) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.37)
- Accepts an optional intent so server-side callers can align session serialization with endpoint selection. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- An optional createTransport interface and provider connection capability support provider-owned realtime transports. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- The optional method returns upstream WebSocket connection details for a server-initiated connection and can select an endpoint using intent. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Enables Anthropic streaming heartbeat parts; pings are disabled by default. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Capability catalogs can include video, reranking, and decision sections, including provider options for those operations. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Providers can transcribe audio from a URL natively; Groq sends HTTP(S) URLs without downloading and re-uploading them. A custom download function retains local download behavior. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Adds an exported server connection type for the experimental realtime model specification. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Adds an exported session intent type for the experimental realtime model specification. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Adds a normalized usage type for realtime events, keeping gross totals and modality buckets separate and reporting duration in seconds. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Accepts an optional intent so server-side callers can align event serialization with endpoint selection. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Accepts shared timestamp granularity settings; explicit provider timing settings take precedence. OpenAI sends timestamp_granularities only with verbose_json. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Optional word timings are exposed separately from transcription segments. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Video generation reports videos delivered directly to caller-managed storage without downloading or synthesizing video bytes. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Introduces named capability sections and request configuration for model entries; provider catalogs also declare accepted options and which models support them. (4.0.35) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.35)
- Adds an experimental SpeechModelV4 extension whose doStream() accepts streamed text parts with optional per-part voice and providerOptions, and returns streamed audio parts. (4.0.33) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.33)
- Adds interrupted to the public finish-reason types. Exhaustive switches, mappings, and custom validation must handle it; interrupted responses preserve partial output without an error solely for the interruption. (4.0.32) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.32)
- Experimental decision calls accept maxOutputTokens and forward it to language-model-backed decisions. (4.0.31) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.31)
- Experimental decision calls accept reasoning and forward it to language-model-backed decisions; language-model adapters keep reasoning disabled when omitted. (4.0.31) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.31)
- Adds support for the Perplexity decisions API. (4.0.30) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.30)
- Adds the box decision question type with image bounds for TypeSafe AI. (4.0.29) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.29)
- Adds an optional shared citation representation to generated text and text-end stream events, preserving citations in core result content and UI message text parts, including validation and persistence. (4.0.27) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.27)
- Embedding functions accept a top-level dimensions setting. (4.0.26) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.26)
- Decision state can contain ordered text, file, and JSON parts. (4.0.25) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.25)
- OpenAI Decisions and language model adapters support image input. (4.0.25) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.25)
- Adds max as a portable reasoning level; exhaustive switches and mappings must handle it. (4.0.23) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.23)
- Adds experimental streaming lifecycle callbacks for speech generation and transcription. (4.0.21) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.21)

### Behavior and default changes

- byteLength can be undefined when a provider fetches an audio URL natively, so telemetry integrations should check for missing values before using it as a number. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Native decision providers warn when maxOutputTokens or reasoning is unsupported. (4.0.31) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.31)
- Public state forms are normalized into an array of parts before provider calls, with text and JSON objects passed as text and json parts. (4.0.25) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.25)
- Decision file bytes are serialized as base64 in state attributes; model-call spans record normalized state parts while outer spans retain public state inputs. (4.0.25) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.25)
- Adds telemetry to speech generation and transcription, including provider usage propagation. (4.0.21) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.21)

### Fixes and other changes

- Boolean criteria may be null in experimental decision question types. (4.0.37) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.37)
- Box instructions may be omitted or null in experimental decision question types. (4.0.37) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.37)
- Empty criteria and null or undefined Score levels are rejected before a request is sent. (4.0.37) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.37)
- TypeSafe decision requests serialize primitive JSON state values as text. (4.0.37) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.37)
- Groq strips media fragments from URLs and falls back to secure local download and file upload if a redirect is rejected. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Access video only when videos is nonempty when generation reports an uploaded outcome. (4.0.36) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.36)
- Non-streaming structured output now handles multiple assistant messages containing JSON by allowing providers to supply separate parsing text, preserving generated content, annotations, conversation history, and token usage. (4.0.34) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.34)
- Streamed input is marked as text so UI clients can display it progressively without JSON parsing; the encoding is preserved when partial UI messages are saved and resumed. (3.0.19, 4.0.28) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.28), [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%403.0.19)
- Raw custom-tool input deltas are restored for consumers that forward them to Responses API clients. (3.0.19, 4.0.28) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.28), [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%403.0.19)
- Gateway keeps its existing string and JSON request format and rejects files. (4.0.25) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.25)
- Shared state is labeled in language-model decision prompts. (4.0.25) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.25)
- Nova 2 calls using portable xhigh now send maxReasoningEffort: 'high' instead of the unsupported 'max', and return a compatibility warning. (4.0.23) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%404.0.23)

## @ai-sdk/provider 2

### Breaking changes

- doGenerate returns a content array. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Image parts are removed from the provider specification. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- logprobs are removed from the provider specification. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- maxTokens is renamed to maxOutputTokens. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- The mimeType field is renamed to mediaType. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Object generation mode is removed. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- The prompt type is removed from the LanguageModelV2 specification. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- providerMetadata inputs are renamed to providerOptions. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- rawRequest is merged into request, so integrations should use request instead. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- The embedding model v2 response gains a body field. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Speech models are upgraded to the v2 specification. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- getSupportedUrls is renamed to supportedUrls for LanguageModelV2. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Tool values use input and output instead of args and result. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Transcription models are upgraded to the v2 specification. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- V1 providers are removed. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)

### New APIs and options

- A v2 embedding model interface is added. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Speech generation is available through experimental_generateSpeech. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Transcription is available through experimental_transcribe. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- ImageModelV2 gains providerMetadata. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Middleware can change the provider, model, and supported URLs. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Provider-defined tools now have a name for future validation. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Raw chunk support is added. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Tool results support arbitrary media types. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- The provider registry adds support for transcription and speech models. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Usage information is refactored and supports reasoning tokens, cached input tokens, and total tokens. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)

### Behavior and default changes

- File content can be provided as binary data or base64, allowing Uint8Array input without manual conversion. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- maxImagesPerCall can be a function returning a number or undefined, optionally as a promise. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Provider-defined tools are collapsed into a single definition. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Warnings are moved into the stream-start part. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)
- Content block streaming now forwards block IDs and streaming start and end events. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)

### Fixes and other changes

- Reasoning parts are refactored and reasoning support is restructured. (2.0.0) — [release notes](https://github.com/vercel/ai/releases/tag/%40ai-sdk/provider%402.0.0)