--- title: Perplexity description: Learn how to use Perplexity with AI Gateway and the direct provider. url: "https://ai-sdk.dev/providers/ai-sdk-providers/perplexity" docs_index: /llms.txt --- > For an index of all documentation, see [/llms.txt](/llms.txt). The [Perplexity](https://www.perplexity.ai) provider offers access to the [Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart). The Agent API can route across models, search the web, call tools, and return cited answers. The provider also supports embeddings and experimental decision models for classification, scoring, and Boolean judgments. You can use Perplexity models through [AI Gateway](/providers/ai-sdk-providers/ai-gateway) (recommended) or connect directly with `@ai-sdk/perplexity`. ```ts provider="perplexity" model="perplexity/sonar" import { generateText } from 'ai'; const { text } = await generateText({ model: "perplexity/sonar", prompt: 'Write a vegetarian lasagna recipe for 4 people.', }); console.log(text); ``` ## Using AI Gateway The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install `ai`: ```bash pnpm add ai ``` Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment: ```bash export AI_GATEWAY_API_KEY=your_api_key_here ``` Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments). See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models. Gateway feature and provider-option support depends on the model and the provider serving the request. See [Gateway provider options](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options). ## Using `@ai-sdk/perplexity` For direct access to Perplexity, install `ai` and `@ai-sdk/perplexity`: ```bash pnpm add ai @ai-sdk/perplexity ``` Set your Perplexity API credential in the `PERPLEXITY_API_KEY` environment variable: ```bash export PERPLEXITY_API_KEY=your_api_key_here ``` AI Gateway offers Sonar models. Use the direct provider for Perplexity Agent API presets, native tools, and model routing, which are documented below. The following sections document the direct `@ai-sdk/perplexity` provider, including its model factories and settings. Gateway model and feature availability can differ. API keys can be obtained from the [Perplexity Platform](https://docs.perplexity.ai). ## Provider Instance You can import the default provider instance `perplexity` from `@ai-sdk/perplexity`: ```ts import { perplexity } from '@ai-sdk/perplexity'; ``` For custom configuration, you can import `createPerplexity` and create a provider instance with your settings: ```ts import { createPerplexity } from '@ai-sdk/perplexity'; const perplexity = createPerplexity({ apiKey: process.env.PERPLEXITY_API_KEY ?? '', }); ``` You can use the following optional settings to customize the Perplexity provider instance: - **baseURL** *string* Use a different URL prefix for API calls. The default prefix is `https://api.perplexity.ai`. - **apiKey** *string* API key that is being sent using the `Authorization` header. It defaults to the `PERPLEXITY_API_KEY` environment variable. - **headers** *Record\* Custom headers to include in the requests. - **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\* Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation. ## Language Models You can create Perplexity models using a provider instance: ```ts import { perplexity } from '@ai-sdk/perplexity'; import { generateText } from 'ai'; const { text } = await generateText({ model: perplexity('low'), prompt: 'What are the latest developments in quantum computing?', }); ``` The Agent API provides the `fast`, `low`, `medium`, `high`, and `xhigh` presets. To select a model directly, pass its Agent API model ID, for example `perplexity('perplexity/sonar')`. These examples call Perplexity directly using `PERPLEXITY_API_KEY`. Passing a plain model string such as `model: 'perplexity/sonar'` to `generateText` or `streamText` uses the [AI Gateway](/providers/ai-sdk-providers/ai-gateway), which has its own model catalog and authentication. Version 5 uses the Agent API exclusively. Legacy Sonar model IDs and provider options are not mapped; see [Migrating from v4 Sonar to v5 Agent API](#migrating-from-v4-sonar-to-v5-agent-api) before upgrading. ### Sources Websites that have been used to generate the response are included in the `sources` property of the result: ```ts import { perplexity } from '@ai-sdk/perplexity'; import { generateText } from 'ai'; const { text, sources } = await generateText({ model: perplexity('low'), prompt: 'What are the latest developments in quantum computing?', }); console.log(sources); ``` ### Agent Tools Pass native Agent API tools through `providerOptions.perplexity.tools`: ```ts import { perplexity, type PerplexityLanguageModelOptions, } from '@ai-sdk/perplexity'; import { generateText } from 'ai'; const { text, sources } = await generateText({ model: perplexity('low'), prompt: 'Summarize recent US federal AI policy from official sources.', providerOptions: { perplexity: { tools: [ { type: 'web_search', filters: { search_domain_filter: [ 'whitehouse.gov', 'congress.gov', 'federalregister.gov', ], search_recency_filter: 'month', }, max_results: 10, search_context_size: 'medium', }, ], } satisfies PerplexityLanguageModelOptions, }, }); ``` Supported native tools are `web_search`, `fetch_url`, `people_search`, `finance_search`, `sandbox`, `mcp`, and `connector`. Agent API presets include preconfigured tools that remain enabled; the `tools` option can add explicit tools or supply tools when using a direct model ID. Search and fetch results are exposed as AI SDK sources. Other native tool traces, including finance, sandbox, and MCP results, are available in `response.body` and raw stream chunks (`include: { rawChunks: true }`). They are not exposed as AI SDK client tool calls. Accounts with zero data retention may reject file-capable tools such as `finance_search` and `sandbox`. AI SDK function tools can be passed through the top-level `tools` option: ```ts import { perplexity } from '@ai-sdk/perplexity'; import { generateText, tool } from 'ai'; import { z } from 'zod'; const result = await generateText({ model: perplexity('low'), prompt: 'What is the weather in San Francisco?', tools: { weather: tool({ description: 'Get the weather for a city', inputSchema: z.object({ city: z.string() }), execute: async ({ city }) => ({ city, temperature: 18 }), }), }, }); ``` ### Provider Options and Metadata The Perplexity provider includes additional metadata in the response through `providerMetadata`. Additional configuration options are available through `providerOptions`. ```ts import { perplexity, type PerplexityLanguageModelOptions, } from '@ai-sdk/perplexity'; import { generateText } from 'ai'; const result = await generateText({ model: perplexity('low'), prompt: 'What are the latest developments in quantum computing?', providerOptions: { perplexity: { max_steps: 5, store: true, reasoning: { effort: 'low' }, } satisfies PerplexityLanguageModelOptions, }, }); console.log(result.providerMetadata); // Example output: // { // perplexity: { // usage: { citationTokens: null, numSearchQueries: 1 }, // images: null, // cost: { totalCost: 0.006, currency: 'USD', ... }, // toolCalls: { search_web: { invocation: 1 } }, // }, // } ``` #### Provider Options The following Agent API options are available: - **instructions** *string* Top-level instructions for the Agent API run. - **tools** *array* Native Agent API tools and their configuration. - **models** *string\[]* A fallback model list for Agent API routing. - **max\_steps** *number* The maximum number of agentic steps. - **max\_tool\_calls** *number* The maximum number of native tool calls. Setting this to `0` disables all preset tools. - **previous\_response\_id** *string* Continue a conversation from an earlier Agent API response. - **store** *boolean* Whether the response can be retrieved later. Setting `store: false` hides it from retrieval; it does not disable persistence, and the response can still be used as a `previous_response_id` continuation source. See Perplexity's [conversation state documentation](https://docs.perplexity.ai/docs/agent-api/conversation-state) for retention behavior and account-specific zero data retention restrictions. - **language\_preference** *string* Preferred response language as an ISO 639-1 language code. - **reasoning** *object* Reasoning configuration. `effort` supports `'minimal'`, `'low'`, `'medium'`, `'high'`, and `'xhigh'`. - **skills** *array* Agent API skill configuration. See the [Perplexity Agent API documentation](https://docs.perplexity.ai/docs/agent-api/quickstart) for details about native request fields. #### Provider Metadata The response metadata includes: - `usage`: `citationTokens` (always `null` for Agent API responses) and the number of search queries - `cost`: Token, tool, and total costs returned by Perplexity - `toolCalls`: Invocation counts grouped by native tool - `images`: Always `null`; the Agent API does not return Sonar image results ### Structured Output `Output.object` and `Output.array` send an Agent API JSON schema response format. JSON output without a schema is not supported. ### Input Images Image URL and data inputs are converted to Agent API `input_image` parts. The Agent API does not provide a Sonar-equivalent PDF input field, so PDF file parts are not supported. ### Migrating from v4 Sonar to v5 Agent API Version 5 is a breaking migration from Sonar Chat Completions to the Agent API. It does not provide legacy model aliases, translate Sonar provider options, or emit migration warnings at runtime. Perplexity supports Sonar Chat Completions only until September 27, 2026. Upgrade language-generation applications to the Agent API before that date; staying on version 4 does not preserve service after the Sonar shutdown. Replace each Sonar model ID with an Agent API preset or direct Agent API model ID. These presets are suggested starting points, not equivalent aliases: a preset can select different models and tools, so cost, latency, and output can change. | v4 Sonar model | Suggested v5 starting point | | --------------------- | --------------------------- | | `sonar` | `fast` | | `sonar-pro` | `low` | | `sonar-reasoning` | `medium` | | `sonar-reasoning-pro` | `medium` | | `sonar-deep-research` | `high` | For example: ```ts // v4 perplexity('sonar-pro'); // v5 perplexity('low'); ``` Move Sonar search and reasoning options to their Agent API locations: | v4 provider option | v5 Agent API option | | ---------------------------------------- | -------------------------------------- | | Domain, recency, and date filters | `tools[].filters` on `web_search` | | `num_search_results` | `tools[].max_results` | | `web_search_options.search_context_size` | `tools[].search_context_size` | | `web_search_options.user_location` | `tools[].user_location` | | `reasoning_effort` | `reasoning.effort` | | `disable_search` | Omit `web_search` for direct model IDs | Preset tools cannot be removed individually. Use a direct model ID without a `web_search` tool when search must be disabled, or set `max_tool_calls: 0` to disable all preset tool calls. The Agent API has no equivalent for Sonar PDF or video inputs, image or video results, `search_language_filter`, or `stream_mode`. Related questions require prompting or structured output. Remove these options during migration. Language requests now use `/v1/agent`. Custom `baseURL` proxies must route that path. Raw responses and streams use the Agent API's typed output and SSE event formats, and Perplexity provider metadata, usage, cost, and source identifiers can differ. The embeddings API is unchanged. For PDF inputs, extract the document text before sending it to the Agent API, or choose another provider that supports PDF input. Move image/video retrieval and language-filtered search to a separate service if your application requires those features. Rework consumers of raw Sonar stream events for typed Agent events. See Perplexity's [migration guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/how-to) for the full API-level comparison. ## Embedding Models You can create models that call the [Perplexity embeddings API](https://docs.perplexity.ai/docs/embeddings/quickstart) using the `.embedding()` factory method. ```ts import { perplexity } from '@ai-sdk/perplexity'; import { embed } from 'ai'; const { embedding } = await embed({ model: perplexity.embedding('pplx-embed-v1-4b'), value: 'sunny day at the beach', }); ``` Perplexity returns **quantized** embeddings (not floating point). Values are decoded to numbers — signed `int8` values (default) or packed bits per byte. Compare `base64_int8` embeddings with cosine similarity and `base64_binary` embeddings with Hamming distance. When the API returns a cost breakdown, it is exposed via `providerMetadata.perplexity.cost` (`inputCost`, `totalCost`, `currency`): ```ts const { embedding, providerMetadata } = await embed({ model: perplexity.embedding('pplx-embed-v1-4b'), value: 'sunny day at the beach', }); console.log(providerMetadata?.perplexity?.cost); // { inputCost: 0.0001, totalCost: 0.0001, currency: 'USD' } ``` ### Provider Options You can pass provider-specific options via the `providerOptions.perplexity` field: ```ts const { embedding } = await embed({ model: perplexity.embedding('pplx-embed-v1-4b'), value: 'sunny day at the beach', providerOptions: { perplexity: { // Matryoshka truncation of the output vector (128 up to the model size). dimensions: 512, // Quantized encoding format. Defaults to 'base64_int8'. encodingFormat: 'base64_int8', }, }, }); ``` The following optional provider options are available for embedding models: - **dimensions** *number* The number of dimensions the resulting output embeddings should have. Ranges from 128 up to the model's full size (1024 for `0.6b` models, 2560 for `4b` models). - **encodingFormat** *'base64\_int8' | 'base64\_binary'* The quantized encoding format returned by the API. Defaults to `base64_int8`. ### Embedding Model Capabilities | Model | Dimensions | Max Values Per Call | | -------------------- | ---------- | ------------------- | | `pplx-embed-v1-0.6b` | 1024 | 512 | | `pplx-embed-v1-4b` | 2560 | 512 | ## Decision Models Use `perplexity.decisionModel()` with [`experimental_decide`](/docs/reference/ai-sdk-core/decide) to call the [Perplexity Decisions API](https://docs.perplexity.ai/docs/decisions/quickstart). This API is experimental and may change in patch releases. ```ts import { perplexity } from '@ai-sdk/perplexity'; import { experimental_decide as decide } from 'ai'; const result = await decide({ model: perplexity.decisionModel('pplx-decider-latest'), state: { review: 'Great sound, but the battery stopped charging.' }, questions: { defect: { type: 'boolean', instructions: 'Does the review report a product defect?', }, sentiment: { type: 'choice', instructions: 'What is the overall sentiment?', criteria: { positive: 'Mostly satisfied', mixed: 'Praise and complaints', negative: 'Mostly dissatisfied', }, }, severity: { type: 'score', instructions: 'How severe is the problem?', criteria: ['Cosmetic', 'Inconvenient', 'Product unusable'], }, }, }); result.answers.defect.probability; // P(true), from 0 to 1 result.answers.sentiment.choice; // 'positive' | 'mixed' | 'negative' result.answers.sentiment.probabilities; result.answers.severity.score; // Expected zero-based level, from 0 to 2 result.answers.severity.probabilities; ``` The provider maps SDK `boolean` questions to Perplexity's native `noul` type and maps the returned `noul` value to `probability`. Choice and Score answers include the API's probability distributions without rounding or normalization. Box questions are unsupported. ### Images and structured state Use ordered text, JSON, and file parts to combine images with other evidence. PNG, JPEG, and WebP images are supported, with at most eight images in the shared state. Core downloads file URLs before the provider converts the image bytes to base64 data URLs: ```ts const result = await decide({ model: perplexity.decisionModel('pplx-decider-latest'), state: [ { type: 'text', text: 'Inspect the product for damage.' }, { type: 'json', value: { product: 'glass vase' } }, { type: 'file', mediaType: 'image/png', data: new URL('https://example.com/product.png'), }, ], questions: { damaged: { type: 'boolean', instructions: 'Is the vase damaged?' }, }, }); ``` You can also preserve an image's position inside a JSON object using Perplexity's native image shape. Such images must already contain base64 data URLs; the SDK does not download URLs embedded inside JSON. Given a base64-encoded PNG in `imageBase64`: ```ts const state = { product: 'glass vase', evidence: { photo: { type: 'image_url', image_url: { url: `data:image/png;base64,${imageBase64}` }, }, }, }; ``` Pass this object as `state` to `decide`. To send a JSON array instead, wrap it in `{ type: 'json', value: records }` within the state parts array. Arrays passed directly as `state` are interpreted as SDK parts. ### Confidence, legends, and response metadata Perplexity's separate confidence values and Score legends are available in `providerMetadata.perplexity`, keyed by question ID. Confidence is distinct from the selected option's probability. Legends preserve the original rubric entries, including structured descriptions. Using the first example's result: ```ts const metadata = result.providerMetadata?.perplexity; console.log(metadata?.confidence); // Choice and Score confidence by question ID console.log(metadata?.legend); // Score index-to-description maps by question ID console.log(result.usage.inputTokens); console.log(result.usage.outputTokens); console.log(result.response.id); // x-request-id, when returned console.log(result.response.modelId); // Model returned by the API ``` ### Decision limits and options The provider validates these limits before sending the decision request: | Input | Limit | | ---------------------- | ----------------------------- | | Questions | 1–128, with nonempty names | | Choice options | 1–255 | | Score levels | 1–10, all non-null | | Images in shared state | At most 8; PNG, JPEG, or WebP | See Perplexity's [request limits](https://docs.perplexity.ai/docs/decisions/quickstart#request-limits) for API-enforced body, token, and image-size limits. The SDK does not resize images. Decision models have no Perplexity-specific provider options. Entries passed in `providerOptions.perplexity` produce unsupported-option warnings and are not sent to the API. Use the standard `abortSignal`, `headers`, and `maxRetries` options on `decide` for cancellation, request headers, and retries. ## Model Capabilities | Model | Image Input | Object Generation | Tool Usage | Tool Streaming | | -------- | ----------- | ----------------- | ---------- | -------------- | | `fast` | ✓ | ✓ | ✓ | ✓ | | `low` | ✓ | ✓ | ✓ | ✓ | | `medium` | ✓ | ✓ | ✓ | ✓ | | `high` | ✓ | ✓ | ✓ | ✓ | | `xhigh` | ✓ | ✓ | ✓ | ✓ | Please see the [Perplexity docs](https://docs.perplexity.ai) for detailed API documentation and the latest updates. --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)