Perplexity

The Perplexity provider offers access to the Agent API. 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 (recommended) or connect directly with @ai-sdk/perplexity.

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-5.5',
  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:

pnpm add ai

npm install ai

yarn add ai

bun add ai

Set an AI Gateway API key in your environment:

export AI_GATEWAY_API_KEY=your_api_key_here

Vercel deployments can also use OIDC authentication. See the AI Gateway provider documentation for configuration and the model catalog for available models.

Gateway feature and provider-option support depends on the model and the provider serving the request. See Gateway provider options.

Using @ai-sdk/perplexity

For direct access to Perplexity, install ai and @ai-sdk/perplexity:

pnpm add ai @ai-sdk/perplexity

npm install ai @ai-sdk/perplexity

yarn add ai @ai-sdk/perplexity

bun add ai @ai-sdk/perplexity

Set your Perplexity API credential in the PERPLEXITY_API_KEY environment variable:

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.

API keys can be obtained from the Perplexity Platform.

Provider Instance

You can import the default provider instance perplexity from @ai-sdk/perplexity:

import { perplexity } from '@ai-sdk/perplexity';

For custom configuration, you can import createPerplexity and create a provider instance with your settings:

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<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation.

Language Models

You can create Perplexity models using a provider instance:

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, 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 before upgrading.

Sources

Websites that have been used to generate the response are included in the sources property of the result:

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:

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:

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.

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 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.

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

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.

For example:

// v4
perplexity('sonar-pro');

// v5
perplexity('low');

Move Sonar search and reasoning options to their Agent API locations:

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 for the full API-level comparison.

Embedding Models

You can create models that call the Perplexity embeddings API using the .embedding() factory method.

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',
});

When the API returns a cost breakdown, it is exposed via providerMetadata.perplexity.cost (inputCost, totalCost, currency):

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:

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

Decision Models

Use perplexity.decisionModel() with experimental_decide to call the Perplexity Decisions API. This API is experimental and may change in patch releases.

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:

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:

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:

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:

See Perplexity's 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