Skip to main content
API7.ai Logo

Perplexity

Connect AISIX AI Gateway to Perplexity so applications can call the search-grounded Sonar models through the gateway's OpenAI-compatible API. AISIX keeps the Perplexity credential on the gateway side. It authorizes model access with caller API keys and allowlists, and applies the same rate-limit and usage-accounting controls as other model aliases.

Perplexity exposes an OpenAI-compatible chat-completions API, so it uses the openai adapter with a Perplexity api_base. AISIX registers no request or response rewrites for Perplexity, so request fields reach the upstream unchanged and responses are normalized with the standard OpenAI-compatible rules.

Prerequisites​

The following examples configure the upstream through the AISIX Cloud Admin API. Before configuring the upstream, prepare the following:

  • A running AISIX managed control plane with an environment and an attached gateway. Follow the AISIX On-Premises Quickstart to set up the stack, create an admin token with write scope, and capture the environment ID.
  • A Perplexity API key. See the Perplexity quickstart for how to create one.

Export the connection details used by every request below:

# Replace with your values
export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="aisix_pat_YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Configure the Perplexity Upstream​

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

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

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

note

api_base is optional for this provider. When it is omitted, the 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.

tip

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.

Verify the Provider Connection​

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 "http://127.0.0.1:3000/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. AISIX forwards the body verbatim, injects the provider key as upstream authentication, and returns the upstream response unchanged:

curl -sS -X POST "http://127.0.0.1:3000/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 provider value, not the alias, and the request body carries the upstream model ID sonar-pro rather than the alias. AISIX still authenticates the caller key and requires it to be allowed a model whose provider is perplexity.

caution

Passthrough is a raw tunnel. It does not parse the response body, so the resulting usage event records zero input and output tokens. Requests sent this way appear in logs but do not contribute to token-based cost accounting or budgets. Use /v1/chat/completions for traffic that must be metered, and reserve passthrough for calls that need the citation payload. See Provider Passthrough.

Set the Reasoning Effort​

sonar-reasoning-pro and sonar-deep-research accept a reasoning_effort field with the values minimal, low, medium, and high. See the Perplexity Sonar Reasoning Pro reference for what each level changes.

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-reasoning-prod, created with model_name set to sonar-reasoning-pro:

{
  "model": "perplexity-sonar-reasoning-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 publishes a chat-only model catalog, which limits the proxy routes a Perplexity alias can serve:

RouteBehavior with a Perplexity alias
/v1/chat/completionsSupported, including stream: true.
/v1/responsesSupported through the Responses bridge over the chat adapter path.
/v1/embeddingsThe openai adapter forwards the request shape, but Perplexity publishes no embedding models, so there is no upstream model to target.
/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.
/passthrough/perplexity/*restSupported. Use it for provider-native request and response shapes.

Two further boundaries affect how you model Perplexity traffic:

  • Tool calling is not recorded as supported for any current Sonar model. Route function-calling workloads to a different alias.
  • AISIX cost metadata is expressed as USD per 1,000 input and output tokens. Perplexity bills sonar-deep-research with per-request, per-citation, and reasoning-token components 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: