spb/zyquo-cloud Public MIT

1<!--2  perplexity.md3  Zyquo Cloud4  Author: Simon-Pierre Boucher5  Mail: contact@spboucher.ai6-->78# Perplexity — Provider Research910Research date: **2026-07-30**. Perplexity has **no `/models` listing for the Sonar chat API** (confirmed 404 with a real key today) — this catalog comes from the official docs: [Models](https://docs.perplexity.ai/docs/sonar/models.md), [Chat Completions reference](https://docs.perplexity.ai/api-reference/sonar-post.md), [Pricing](https://docs.perplexity.ai/docs/getting-started/pricing.md), [Rate limits](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md), [Stream mode](https://docs.perplexity.ai/docs/sonar/pro-search/stream-mode.md), [Agent API migration](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/overview.md).1112> **Strategic note (July 2026):** Perplexity is steering users from "Sonar Chat Completions" to a new **Agent API** (`POST https://api.perplexity.ai/v1/agent`, presets `fast/low/medium/high/xhigh`, third-party models incl. GPT/Claude/Gemini/Grok/Kimi). The migration page says Sonar Chat Completions "remains supported" with **no announced sunset date**, but the rate-limits page already labels it "Sonar API (Deprecated)". Zyquo Cloud ships on the OpenAI-compatible `/chat/completions` Sonar API (fits our shared client), and should keep the Agent API on the roadmap.1314---1516## 1. Base URL & Endpoints1718- **Base URL:** `https://api.perplexity.ai`19- Chat completions (what Zyquo Cloud uses): `POST https://api.perplexity.ai/chat/completions`20- No model-listing endpoint for the chat API (see §8).21- Other product APIs, not used: Agent API `POST /v1/agent` (and `GET /v1/models` — Agent API models only), Search API, Embeddings API.2223## 2. Authentication2425Standard Bearer (confirmed live):2627```28Authorization: Bearer pplx-...29```3031## 3. Chat Model Catalog3233The [API reference](https://docs.perplexity.ai/api-reference/sonar-post.md) enumerates exactly **four** valid `model` values. All are search-grounded chat models with streaming; none accept image input (`return_images` returns image *search results*, it is not vision input). **`sonar-reasoning` (non-Pro) is gone from the current docs enum — treat as removed/deprecated.**3435Pricing is official ([pricing doc](https://docs.perplexity.ai/docs/getting-started/pricing.md)); note the **per-request fee scaled by `search_context_size`** on top of token fees — Zyquo Cloud's cost estimator must include it. Context windows are not stated in the current official docs; figures below are from trackers ([OpenRouter](https://openrouter.ai/perplexity)) — **unverified**.3637| API ID | Context (unverified) | Max output | $/1M in | $/1M out | Request fee /1K (low/med/high ctx) | Capabilities |38|---|---|---|---|---|---|---|39| `sonar` | 128K | ≤128,000 (API cap) | $1 | $1 | $5 / $8 / $12 | Fast grounded Q&A; streaming, JSON schema output, citations |40| `sonar-pro` | 200K | 8,000 (unverified) | $3 | $15 | $6 / $10 / $14 | "Complex queries and follow-ups"; streaming, citations |41| `sonar-reasoning-pro` | 128K | — | $2 | $8 | $6 / $10 / $14 | Chain-of-thought (`<think>` block in content); citations |42| `sonar-deep-research` | 128K | — | $2 | $8 | Search queries $5/1K + citation tokens $2/1M + reasoning tokens $3/1M | Long-running exhaustive research reports; `reasoning_effort` applies |4344## 4. Request / Response Format4546**OpenAI-compatible request shape with Perplexity extensions.** Minimal request:4748```json49POST https://api.perplexity.ai/chat/completions50Authorization: Bearer pplx-...51Content-Type: application/json5253{54  "model": "sonar",55  "messages": [{ "role": "user", "content": "How many stars are in the Milky Way?" }]56}57```5859Response = standard `chat.completion` plus Perplexity-specific top-level fields (all from the [API reference](https://docs.perplexity.ai/api-reference/sonar-post.md)):6061- `citations`: array of source URLs ("URLs of sources used to generate the response") — render as Zyquo Cloud's numbered chips.62- `search_results`: array of result objects (title/url/date) used for context — richer than `citations`; prefer it for chip tooltips.63- `images` (when `return_images: true`), `related_questions` (when `return_related_questions: true`).64- `usage` is extended: `prompt_tokens`, `completion_tokens`, `total_tokens`, `search_context_size`, `citation_tokens`, `num_search_queries`, `reasoning_tokens`, and a **`cost` object** (input/output/reasoning/request/citation/search-queries costs + `total_cost`, USD) — Zyquo Cloud can display exact billed cost instead of estimating.65- Reasoning models emit CoT inside `<think>…</think>` in `content` (parse into the collapsible thinking section); `sonar-deep-research` reports `reasoning_tokens` in usage.6667Deviations from OpenAI: no `n`, no `presence_penalty`/`frequency_penalty`/`top_k` in the current schema (historical `top_k`/penalties have been dropped — send none); no vision/image input; no tool/function calling on the Sonar chat API.6869## 5. Streaming (SSE)7071`"stream": true` → SSE `data:` lines. Two formats via `stream_mode` ([stream-mode doc](https://docs.perplexity.ai/docs/sonar/pro-search/stream-mode.md)):7273- `full` (default): every chunk is `chat.completion.chunk` and each chunk carries the accumulated `message` server-side — **search results/citations appear repeatedly during the stream**; higher bandwidth. OpenAI-style `delta` parsing still works.74- `concise`: delta-only, with distinct chunk `object` types: `chat.reasoning` (live reasoning steps) → `chat.reasoning.done` ("includes all search results — web, images, videos") → `chat.completion.chunk` (answer deltas) → `chat.completion.done` (final metadata; "cost information is only available in the `chat.completion.done` chunk").7576Practical rule for Zyquo Cloud's shared SSE parser: with default `full` mode, take `citations`/`search_results`/`usage` from the **final** chunk. `sonar-deep-research` streams slowly (long research phase) — needs the long read-timeout path.7778## 6. Special Parameters (Perplexity extensions)7980From the [API reference](https://docs.perplexity.ai/api-reference/sonar-post.md):8182- Generation: `max_tokens` (0 < n ≤ 128,000), `temperature` (0–2), `top_p` (0–1), `stop`, `stream`, `stream_mode` (`full|concise`), `reasoning_effort` (`minimal|low|medium|high` — for reasoning/deep-research models), `response_format` (`text` or `json_schema` structured output), `language_preference` (ISO 639-1).83- Search behavior: `disable_search` (bool), `enable_search_classifier` (bool — model decides if search is needed), `search_mode` (`web|academic|sec`), `web_search_options` `{ search_context_size: low|medium|high, search_type: fast|pro|auto, user_location, image_results_enhanced_relevance }`.84- Search filters: `search_domain_filter` (array; `-domain` excludes), `search_language_filter` (ISO 639-1 array), `search_recency_filter` (`hour|day|week|month|year`), `search_after_date_filter` / `search_before_date_filter` and `last_updated_after_filter` / `last_updated_before_filter` (all `MM/DD/YYYY`), `image_domain_filter`, `image_format_filter`.85- Response extras: `return_images` (bool), `return_related_questions` (bool).8687UI mapping: expose `search_mode`, recency filter, domain filter, `search_context_size`, `return_images`, `return_related_questions`, and `reasoning_effort` in Zyquo Cloud's per-conversation parameter sheet for Perplexity only.8889## 7. Rate Limits & Errors9091[Rate limits doc](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md): six tiers by **cumulative lifetime spend** — Tier 0 $0, T1 $50+, T2 $250+, T3 $500+, T4 $1,000+, T5 $5,000+. Sonar API tiered RPM historically ranged "from 5 RPM (deep-research at Tier 0) to 100 RPM (Tier 5)" (page now brands the Sonar table "Deprecated" — exact current per-model RPM: unverified). On breach: HTTP **429 "Too Many Requests"**, with continuous token-bucket refill (retry after short backoff).9293Error format: OpenAI-style JSON error body with HTTP statuses 400 (invalid model/params), 401 (bad key), 429 (rate limit). Exact error JSON schema is not published in the docs — **unverified**; handle by HTTP status + message string defensively.9495## 8. `/models` Listing9697**No — for the chat API.** `GET https://api.perplexity.ai/models` returns **404** (confirmed live today with a real key). The four Sonar model IDs must ship hard-coded in `ModelCatalog` from `docs/PROVIDERS.md`.9899Caveat: the docs do describe `GET https://api.perplexity.ai/v1/models` ([reference](https://docs.perplexity.ai/api-reference/models-get.md)), but it "returns model identifiers that can be used with the `POST /v1/agent` endpoint" — i.e. **Agent API** models (claude-opus-5, gpt-5.6-sol, gemini-3.6-flash, grok-4.5, kimi-k3, glm-5.2, sonar, …), not Sonar chat-completions models. Do not use it to populate the Perplexity chat catalog.100101## Vision Input102103Not supported on the Sonar chat models — no `image_url` content parts. (`return_images` only returns image *search results*.) Zyquo Cloud must mark all Perplexity models as non-vision.104