Provider Options
Purpose and Scope
Provider options are the escape hatch for model features that are not part of the AI SDK’s portable settings surface. The common settings layer covers cross-provider concerns, while provider options let a request opt into capabilities such as OpenAI reasoning controls, provider-specific summaries, caching knobs, or other advanced behavior exposed by an individual model provider. The documented contract is intentionally namespaced: a request passes a provider-keyed object, and only the object for the active provider is applied. That keeps one call shape usable even when model selection changes at runtime.
Sources: content/docs/02-foundations/06-provider-options.mdx
This page focuses on how those request-level settings relate to provider instances, AI Gateway, provider registries, realtime sessions, and returned metadata. In normal text and object generation calls, the option travels with the model invocation. In custom provider setups, the same setting can be pre-applied through middleware so an application can expose stable model aliases. In realtime flows, provider configuration is split between the short-lived token request and the browser session configuration, which means sensitive authentication remains on the server while the browser receives only a client-safe connection artifact.
Sources: content/docs/02-foundations/06-provider-options.mdx, content/docs/03-ai-sdk-core/45-provider-management.mdx, content/docs/03-ai-sdk-core/36-realtime.mdx
Relevant Source Files
- content/docs/02-foundations/06-provider-options.mdx — Defines the provider options concept, the providerOptions request property, OpenAI examples, reasoning effort values, reasoning summaries, and provider metadata access.
- content/providers/01-ai-sdk-providers/00-ai-gateway.mdx — Documents AI Gateway model strings, the gateway provider instance, createGateway configuration, authentication choices, headers, base URL, fetch, and metadata cache refresh settings.
- content/docs/03-ai-sdk-core/36-realtime.mdx — Shows realtime setup endpoints, experimental realtime token creation, AI Gateway realtime usage, sessionConfig, and tool definition attachment.
- content/docs/03-ai-sdk-core/45-provider-management.mdx — Explains customProvider, defaultSettingsMiddleware, wrapLanguageModel, model aliases, limited model sets, fallback providers, and default providerOptions.
- content/docs/07-reference/01-ai-sdk-core/23-get-realtime-tool-definitions.mdx — Provides the API reference for converting AI SDK tools into provider-neutral realtime tool definitions.
- content/docs/07-reference/01-ai-sdk-core/40-provider-registry.mdx — Provides the API reference for createProviderRegistry, model lookup methods, separators, files, and skills interfaces.
Request-Level Configuration Model
The primary request-level entry point is the provider option map passed to generation functions such as generate text and stream text. The example shape uses an OpenAI model and an OpenAI namespace containing a reasoning effort value. Because the option is provider-namespaced, an application can include option groups for more than one provider without rewriting the call every time it switches from one active model to another. The docs also point readers to message and message-part provider options, which are useful when only a particular prompt segment needs provider-specific handling rather than the entire call.
Sources: content/docs/02-foundations/06-provider-options.mdx
OpenAI reasoning options illustrate the difference between portable settings and provider-specific control. The foundation docs recommend the top-level reasoning parameter when the goal is simply to express reasoning intent across providers. The OpenAI provider option remains useful when a caller needs exact OpenAI semantics, such as the documented reasoning effort values none, minimal, low, medium, high, and xhigh. The docs call out that some values are model-limited, so callers should treat unsupported combinations as configuration errors rather than generic degradation. Returned provider metadata can expose OpenAI-specific usage details, including reasoning token information on the final step.
Sources: content/docs/02-foundations/06-provider-options.mdx
Provider Instances, Gateway, and Registries
AI Gateway changes where provider choice is expressed, but not the basic idea that request configuration follows the selected model. The Gateway provider lets callers use a plain model string in creator and model-name form, or a gateway provider instance imported from the main package. For advanced setups, a custom Gateway instance can be created with configuration fields for base URL, API key or Vercel access token, team scope, custom headers, a custom fetch implementation, and metadata cache refresh timing. This is the right layer for authentication, routing, test interception, or application-wide Gateway defaults.
Sources: content/providers/01-ai-sdk-providers/00-ai-gateway.mdx
Provider management is the main way to avoid repeating the same provider options on every call. The provider management docs show custom providers that wrap Gateway language models with default settings middleware, including default provider option maps. This can create a plain alias for a model with high reasoning, expose a separate high-reasoning alias, or limit a system to a curated set of text, embedding, and reasoning models. A fallback provider can remain available, but omitting one intentionally prevents access to unlisted models and makes the model surface easier to audit.
Sources: content/docs/03-ai-sdk-core/45-provider-management.mdx
The provider registry complements custom providers by assigning stable provider prefixes and resolving model IDs through a central registry. Its default model ID format combines a provider ID and model ID with a colon, and the separator can be customized when an application needs a different convention. The same registry can provide language, embedding, image, and video model handles, and it can expose a provider’s files and skills interfaces. This is valuable when provider options are configured behind aliases, because application code can request a concise model ID while central setup owns provider-specific defaults.
Sources: content/docs/07-reference/01-ai-sdk-core/40-provider-registry.mdx, content/docs/03-ai-sdk-core/45-provider-management.mdx
Realtime Provider Options and Metadata Flow
Realtime calls use a related but distinct configuration flow. The browser should not hold the long-lived provider credential; instead, it calls a server setup endpoint. The server creates a short-lived realtime token through the provider’s experimental realtime token API, optionally passing a session configuration. That session configuration can include instructions, audio transcription settings, voice, turn detection, and tool definitions. When AI Gateway is used for realtime, the server creates a Gateway realtime token and the browser constructs the matching Gateway realtime model, keeping the secret creation step server-side while still allowing client-side realtime interaction.
Sources: content/docs/03-ai-sdk-core/36-realtime.mdx
Tools in realtime sessions show how provider-neutral data is prepared before provider-specific transport begins. The reference for experimental realtime tool definitions describes a conversion function that accepts an AI SDK tool set and optional tool context, resolves dynamic descriptions, converts input schemas to JSON schema, and returns function-style realtime definitions. Provider tools are skipped because realtime sessions expect regular function definitions in the session configuration. Execution is intentionally separate: the realtime hook handles tool calls in the application, and the application returns outputs, so conversion does not imply automatic server-side execution.
Sources: content/docs/07-reference/01-ai-sdk-core/23-get-realtime-tool-definitions.mdx, content/docs/03-ai-sdk-core/36-realtime.mdx
Compact Reference
| Surface | Concrete names and fields | Source-level contract |
|---|---|---|
| Request provider options | providerOptions, openai.reasoningEffort, openai.reasoningSummary | Pass provider-specific settings on model calls; options are namespaced and only the active provider’s namespace is used. |
| OpenAI reasoning values | none, minimal, low, medium, high, xhigh | Controls reasoning behavior for supported reasoning models; unsupported model and value combinations can fail. |
| Provider metadata | finalStep.providerMetadata.openai.reasoningTokens | Provider-specific result metadata can be read from the final step when the provider returns it. |
| Gateway model selection | model string creator/model-name, gateway(modelId), createGateway(options) | Gateway can be used implicitly through model strings or explicitly through a provider instance. |
| Gateway instance options | baseURL, apiKey, teamIdOrSlug, headers, fetch, metadataCacheRefreshMillis | Configure authentication, routing, request interception, custom headers, and metadata refresh behavior. |
| Provider defaults | customProvider, wrapLanguageModel, defaultSettingsMiddleware, fallbackProvider | Preconfigure providerOptions and model aliases centrally instead of repeating options per request. |
| Registry lookup | createProviderRegistry, languageModel, embeddingModel, imageModel, videoModel, files, skills, separator | Resolve provider-prefixed model IDs and provider interfaces from a central registry. |
| Realtime tools | experimental_getRealtimeToolDefinitions, tools, toolsContext | Convert AI SDK tools into provider-neutral realtime function definitions for session setup. |
Sources: content/docs/02-foundations/06-provider-options.mdx, content/providers/01-ai-sdk-providers/00-ai-gateway.mdx, content/docs/03-ai-sdk-core/45-provider-management.mdx, content/docs/07-reference/01-ai-sdk-core/40-provider-registry.mdx, content/docs/07-reference/01-ai-sdk-core/23-get-realtime-tool-definitions.mdx
Implementation Guidance and Next Steps
Use provider options at the narrowest layer that matches the reason for the setting. If a single request needs a provider feature, pass the namespaced option directly on that call. If a whole product path should always use the same reasoning mode, define a custom provider alias or wrapped model with default settings middleware. If many teams or routes share providers, put those providers in a registry and reference models by stable IDs. For realtime, keep token creation and any credential-bearing provider setup on the server, and return only the short-lived token and session data needed by the browser.
Sources: content/docs/02-foundations/06-provider-options.mdx, content/docs/03-ai-sdk-core/45-provider-management.mdx, content/docs/03-ai-sdk-core/36-realtime.mdx
When debugging provider option behavior, first verify the active model provider and namespace match. A correctly shaped option object for one provider is intentionally ignored when another provider is active, so silent non-application can mean the request selected a different provider than expected. Next, check whether the option is better represented by a portable top-level setting, especially for reasoning. Finally, inspect returned provider metadata when available, because it is the clearest confirmation that the provider processed a provider-specific feature and returned provider-specific accounting or details.
Sources: content/docs/02-foundations/06-provider-options.mdx