Skip to main content
API7.ai Logo

Perplexity

Perplexity Sonar provides search-grounded models that combine language-model responses with web retrieval. Applications call Sonar through stable AISIX aliases while the gateway holds the Perplexity credential.

Prerequisites​

Before starting, prepare the following:

  • One AISIX setup:
    • For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
    • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
  • A Perplexity API key. See the Perplexity quickstart for how to create one.
  • curl and jq.

Configure with AISIX Cloud​

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create a provider key, model alias, and caller API key for the Perplexity-backed chat-completions route.

Because Perplexity exposes an OpenAI-compatible chat-completions API, AISIX connects through the openai adapter and uses the Perplexity API root as api_base. AISIX registers no Perplexity-specific request or response rewrites.

Create a Provider Key​

Create the provider key that stores the Perplexity credential and API root:

# Replace with your values
export PERPLEXITY_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "perplexity-prod",
    "provider": "perplexity",
    "api_key": "'"${PERPLEXITY_API_KEY}"'",
    "api_base": "https://api.perplexity.ai",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider is perplexity. The AISIX Cloud Admin API derives the adapter from the catalog provider; the adapter field is only accepted on BYO provider keys.

❷ api_key stores the Perplexity API key. It follows the credential-handling behavior in Provider Keys.

❸ api_base is the bare host https://api.perplexity.ai, the base URL Perplexity documents for OpenAI SDK clients. Its OpenAI-compatible chat-completions route is served at /chat/completions with no version segment, so the base carries no version suffix. AISIX appends the endpoint path, producing https://api.perplexity.ai/chat/completions.

api_base is optional for this provider. When it is omitted, the AISIX Cloud Admin API fills in https://api.perplexity.ai. Setting it explicitly keeps the upstream root visible on the resource. The value must never end up empty: for an openai-adapter provider other than openai, AISIX refuses to fall back to api.openai.com and returns an upstream configuration error instead, so a Perplexity credential is never sent to the public OpenAI host.

AISIX strips a trailing endpoint segment from api_base, so pasting the full documented endpoint URL https://api.perplexity.ai/chat/completions resolves to the same base. A trailing slash is also removed.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model​

Perplexity model IDs name a search tier rather than a parameter count or a release date. They are bare names with no vendor namespace and no dated snapshot suffix: sonar for fast grounded answers, sonar-pro for broader retrieval and stronger synthesis, sonar-reasoning-pro for cited multi-step reasoning, and sonar-deep-research for long-running research reports.

Create the model alias callers will send in requests:

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "perplexity-sonar-pro-prod",
    "model_name": "sonar-pro",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name is the alias callers send in model.

❷ model_name is the Perplexity model ID, for example sonar-pro or sonar.

❸ provider_key_id attaches the alias to the Perplexity provider key.

Create a Caller API Key​

Create the caller API key that can access the model alias. The gateway generates the key value; the plaintext is returned once in the create response, so capture it now:

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "perplexity-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

The allowed_models value references the model by its ID, so the key can only access the alias you created. After the write, the configuration projects to attached gateways automatically.

Configure with the Open-Source AISIX Gateway​

Export the upstream credential and choose the caller API key that applications will send to the gateway:

export PERPLEXITY_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

Create a complete declarative resources file for this provider:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "perplexity-prod"
    provider: "perplexity"
    adapter: "openai"
    api_key: ${PERPLEXITY_API_KEY}
    api_base: "https://api.perplexity.ai"

models:
  - display_name: "perplexity-sonar-pro-prod"
    provider: "perplexity"
    model_name: "sonar-pro"
    provider_key: "perplexity-prod"

api_keys:
  - display_name: "perplexity-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "perplexity-sonar-pro-prod"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection​

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

Send a chat-completions request through the AISIX proxy. Sonar answers from live web search, so ask something that requires current information:

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "perplexity-sonar-pro-prod",
    "messages": [
      {
        "role": "user",
        "content": "Summarize the latest news about AI gateways in two sentences."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias perplexity-sonar-pro-prod. If the request fails, check the provider key api_key, api_base, and the Perplexity model ID in model_name.

Retrieve Search Citations​

Sonar responses carry their sources in citations and search_results at the top level of the Perplexity response body, alongside choices. Those fields are Perplexity extensions rather than part of the OpenAI chat-completions shape. AISIX normalizes chat-completions responses into the canonical OpenAI shape, so the two fields do not reach the caller on /v1/chat/completions.

When an application needs the source list, call the provider-native route instead. The /passthrough/perplexity paths on this page assume a passthrough route claiming that prefix with https://api.perplexity.ai as its target_url; grant the route name on the caller key's allowed_routes. AISIX forwards the body verbatim, injects the provider key credential bound to the route, and returns the upstream response unchanged:

curl -sS -X POST "$AISIX_PROXY/passthrough/perplexity/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "messages": [
      {
        "role": "user",
        "content": "Summarize the latest news about AI gateways in two sentences."
      }
    ]
  }'

The perplexity path segment is the route's claimed prefix — by convention the provider name — not the alias, and the request body carries the upstream model ID sonar-pro rather than the alias. AISIX still authenticates the caller key, which must grant the route name in its allowed_routes list.

note

The gateway detects the request's chat envelope (messages) automatically, so usage figures from the Sonar response are recorded on the usage event best-effort and token-based accounting covers this traffic. See Passthrough Routes.

Set the Reasoning Effort​

The Sonar request schema exposes a reasoning_effort field with the values minimal, low, medium, and high, but model-specific documentation can narrow the accepted values. For example, Perplexity currently documents low, medium, and high for sonar-deep-research.

AISIX forwards request fields it does not model to the upstream unchanged, so add the field to the chat-completions body. The following example assumes a second alias, perplexity-sonar-research-prod, created with model_name set to sonar-deep-research:

{
  "model": "perplexity-sonar-research-prod",
  "messages": [{ "role": "user", "content": "Compare the two proposals." }],
  "reasoning_effort": "high"
}

AISIX registers no response.reasoning_field mapping for Perplexity, so it does not lift a Perplexity-specific reasoning field into the canonical reasoning_content slot. Reasoning output reaches the caller wherever Perplexity places it in the standard response content. If a future Perplexity model streams reasoning on a separate delta path, set response.reasoning_field on the provider key.

Endpoint and Cost Boundaries​

Perplexity now publishes separate Sonar, Agent, Search, and Embeddings APIs. Their path prefixes differ, so the Sonar provider key configured in this guide cannot serve every API through a normalized AISIX route.

RouteBehavior with a Perplexity alias
/v1/chat/completionsSupported, including stream: true.
/v1/completionsNot available. Perplexity does not publish the legacy prompt-completions route.
/v1/responsesSupported through the Responses bridge over Sonar chat completions, not Perplexity's native Agent API. Fields without a chat equivalent are ignored. Use /passthrough/perplexity/v1/responses for the native Responses-compatible contract and send an Agent API model ID or preset rather than an AISIX alias.
/v1/messagesCompatible Anthropic-shaped requests are supported through translation to Sonar chat completions. /v1/messages/count_tokens is unavailable because it requires an Anthropic-protocol provider key.
/v1/embeddingsNot with the Sonar provider key above: AISIX would append /embeddings to the bare host, while Perplexity publishes standard embeddings at /v1/embeddings. Create a separate provider key with api_base: https://api.perplexity.ai/v1 and an alias for pplx-embed-v1-0.6b or pplx-embed-v1-4b.
/v1/images/generationsRejected. The route accepts only models whose configured provider is openai.
/v1/rerankRejected. The route allowlist is openai, cohere, and jina.
/v1/videosRejected. The route allowlist does not include perplexity.
/v1/modelsReturns caller-accessible AISIX aliases. Use /passthrough/perplexity/v1/models for the current Agent API model list.
/passthrough/perplexity/searchCalls Perplexity's native Search API and returns raw search results.
/passthrough/perplexity/*restAvailable through a configured passthrough route. Use it for provider-native request and response shapes.

Perplexity's standard embedding models return quantized base64 strings rather than float arrays. AISIX preserves that response representation. Callers must decode base64_int8 or base64_binary and use the similarity metric documented by Perplexity.

Two further boundaries affect how you model Perplexity traffic:

  • Sonar does not expose caller-defined function tools. Sonar Pro Search can invoke Perplexity-managed search and URL-fetching tools, while the Agent API provides the broader tool contract. Route custom function-calling workflows through a compatible Agent API model or another provider.
  • AISIX cost metadata is expressed as USD per 1,000 input and output tokens. Perplexity bills sonar-deep-research for citation tokens, search queries, and reasoning tokens in addition to prompt and completion tokens, so a token-only estimate understates the real spend for that model. Treat gateway cost figures for sonar-deep-research as a lower bound and reconcile against Perplexity billing.

Next Steps​

You have now connected AISIX to Perplexity and verified the model alias. Continue with these guides: