Risposta diretta. Oggi Perplexity offre agli sviluppatori cinque API sotto una sola chiave e un solo host (api.perplexity.ai): Agent API (una risposta già scritta, con citazioni), Search API (risultati web ordinati, senza modello), Decisions API (probabilità su domande sì/no o a scelta multipla), Embeddings API (vettori) e Orchestrator API (chiamate nei formati OpenAI o Anthropic, in anteprima privata). Se parti da zero, la scelta si riduce a una domanda: ti serve un testo finito con fonti (Agent API) oppure ti servono le fonti grezze da dare al tuo modello (Search API)? Le vecchie chiamate «Sonar» sono confluite nell'Agent API: chi ha codice su chat.completions deve migrare.
Non sono affiliato a Perplexity, e questo sito non usa Perplexity per le proprie funzioni AI: qui è l'oggetto della serie, non un fornitore. Il perché la serie interessa anche chi pubblica contenuti lo spiegano gli ultimi due articoli.
Ogni fatto sul prodotto, in questo articolo come nei successivi, viene dalla documentazione ufficiale per sviluppatori aperta il 13 novembre 2026 (l'elenco con ciò che ne ho preso è in fondo). Non ho una chiave, non ho chiamato il prodotto e non riporto nessuna sua risposta come se fosse vera: gli esempi di risposta sono schemi che dichiaro tali, e gli script che trovi qui girano senza rete. Nomi dei modelli, prezzi e limiti cambiano nell'arco di mesi, quindi ricontrolla la pagina prima di scrivere una cifra in un preventivo.
Le cinque API in una tabella
Secondo la pagina «Overview», le cinque API condividono chiave e host e ciascuna ha il proprio endpoint. La chiave si genera nella console (console.perplexity.ai).
| API | Che cosa restituisce | Endpoint | Quando ha senso |
|---|---|---|---|
| Agent API | Una risposta completa con citazioni; il modello cerca, ragiona e usa strumenti | POST /v1/agent (il percorso /v1/responses è accettato) | Vuoi una risposta pronta e accetti che il numero di passi, e quindi il costo, vari |
| Search API | Risultati web ordinati in JSON (title, url, date, snippet con il testo estratto); nessun modello | POST /search | Hai già un modello e una pipeline RAG e ti manca solo il recupero |
| Decisions API | Probabilità calibrate su domande sì/no, a scelta multipla o a rubrica, su testo, JSON o immagini | POST /v1/decisions | Vuoi una probabilità da confrontare con una soglia, non un'etichetta da interpretare |
| Embeddings API | Vettori per ricerca semantica e RAG | vedi il suo quickstart | Hai un indice vettoriale tuo |
| Orchestrator API | Risposte nei formati Chat Completions, Responses o Messages, instradate a un deployment sano | base https://api.perplexity.ai/orchestrator/v1 | Anteprima privata: oggi non è una scelta di partenza |
La tabella si legge per colonne di responsabilità: più a sinistra del tuo codice sta la pipeline (Agent API), meno ne scrivi e meno la controlli; più a destra (Search, Embeddings), più pezzi sono tuoi. Sull'Orchestrator le due pagine ufficiali che ho letto descrivono il catalogo in modo diverso (una dice «qualsiasi modello del catalogo», l'altra «modelli open-weight ospitati da Perplexity»): è un motivo in più per non costruirci sopra finché è un'anteprima. Fonti: Overview e Quickstart, 13 novembre 2026.
Agent API contro Search API: il trade-off vero
È la decisione che pesa di più, e non è una questione di qualità ma di chi controlla cosa. Le due strade si distinguono in tre punti:
- Con l'Agent API deleghi tutto: query di ricerca, lettura delle pagine, ragionamento, formulazione. Il livello
effortfissa un tetto di passi (1 afast, 5 alow, 15 amedium, 40 ahigh, 300 axhigh), ma dentro il tetto è il modello a decidere quanto cercare. - Con la Search API controlli ogni passaggio: cosa cerchi, quanti risultati tieni, con quale modello e prompt li trasformi in testo, come mostri le fonti. Scrivi più codice, ma ogni richiesta riuscita costa una cifra nota (5,00 dollari ogni mille, 1,00 con la ricerca «fast»).
- Nel mezzo sta la scelta che si dimentica: puoi usare la Search API per il recupero e il tuo modello per la risposta oggi, e passare all'Agent API per un solo flusso domani, perché le chiavi e l'host sono gli stessi.
Regola pratica che applico: se la risposta è l'interfaccia del prodotto (un assistente, un riassunto con fonti), parti dall'Agent API; se è una parte di una pipeline che hai già (RAG, verifica di un'affermazione, arricchimento di dati), parti dalla Search API. L'articolo 2 entra nell'Agent API, il 3 nella Search API: scegli leggendo quello che corrisponde al tuo caso e salta l'altro senza perdere il filo.
Quanto costa, per ciò che è documentato
La pagina «Pricing» elenca le tariffe in modo diverso per ciascuna API, ed è meglio leggerle accanto alla loro unità di misura:
- Ricerca web nell'Agent API: 0,0025 dollari a invocazione (2,50 ogni mille), 0,001 con
search_type: "fast".fetch_url: 0,0005 a invocazione. - Search API: 5,00 dollari ogni mille richieste riuscite, 1,00 con
search_type: "fast". Una richiesta con fino a cinque query conta come una sola unità di fatturazione; richieste non valide, respinte per limite di frequenza o fallite a monte non si pagano. - Embeddings, per milione di token: da 0,004 dollari (
pplx-embed-v1-0.6b, 1024 dimensioni) a 0,05 (pplx-embed-context-v1-4b, 2560 dimensioni). - Decisions API: 0,02 dollari per milione di token in ingresso per
pplx-decider-v1.3, 0,01 per la versione flash; i token in uscita sono gratuiti.
L'Agent API è l'unica in cui il costo ha due parti che crescono insieme: i token del modello e gli strumenti invocati. I token si pagano alle tariffe pubblicate pagina per pagina nella lista dei modelli (per esempio openai/gpt-6-luna, il modello che il livello low dichiara, è a 0,10 dollari per milione di token in ingresso e 0,50 in uscita fino a 272.000 token di contesto); gli strumenti si sommano. L'articolo 2 mostra il conto completo con uno script. Fonti: Pricing e Agent API Models, 13 novembre 2026.
E «Sonar»? Dove sono finiti i vecchi modelli
Se hai già visto codice con model="sonar-pro" e chat.completions, quello è il vecchio mondo. La pagina di migrazione dice che il supporto alle chat completions Sonar è terminato il 27 settembre 2026, che le richieste sincrone e in streaming continuano a funzionare perché Perplexity le riformula come richieste Agent API, con un'introduzione graduale modello per modello, e che le richieste asincrone non sono riformulate e non sono più supportate (vanno spostate sulla modalità background). Un membro dello staff, nel forum degli sviluppatori il 10 settembre 2026, ha risposto a chi chiedeva se il vecchio endpoint sarebbe rimasto dopo il 27 settembre che l'endpoint delle chat completions Sonar sarebbe stato ritirato quel giorno. Il comportamento di una richiesta sincrona può quindi cambiare senza che tu tocchi una riga: l'articolo 4 spiega come accorgertene e come migrare.
Orchestrator API e Comet: due cose che non sono la tua prima scelta
L'Orchestrator API è descritta come «private preview»: accetta chiamate nei formati Chat Completions, Responses o Messages e le instrada a un deployment sano. Una anteprima privata non è una base su cui costruire un servizio in produzione, e non posso verificarla senza accesso: la nomino perché compare nella panoramica e non le dedico un articolo.
Comet è un browser con un assistente che agisce al posto dell'utente. La pagina ufficiale non mi ha risposto: ha rifiutato la richiesta automatica con HTTP 403. Per questo non scrivo nulla sulle sue funzioni, sulle piattaforme o sui prezzi, e dal punto di vista di chi sviluppa lo tratto come un cliente, non come una superficie di integrazione. Una cosa però riguarda chiunque pubblichi pagine web, e la fonte l'ho letta intera: nel post «Agentic Browser Security: Indirect Prompt Injection in Perplexity Comet», pubblicato il 20 agosto 2025, i ricercatori di Brave descrivono come istruzioni nascoste in una pagina (testo bianco su bianco, commenti HTML, o il commento di un utente dietro un tag «spoiler» su Reddit) venissero eseguite dall'assistente durante un «riassumi questa pagina», fino a una dimostrazione di furto di account su un esempio costruito da loro.
Prima di trarne una regola conviene pesare la fonte. È un'analisi pubblicata da un concorrente (Brave sviluppa un proprio browser con assistente), con una dimostrazione costruita dagli autori e senza revisione indipendente: è una prova che il difetto era riproducibile, non una misura della sua diffusione. La cronologia del post è precisa: segnalazione a Perplexity il 25 luglio 2025, correzione iniziale il 27 luglio giudicata incompleta il 28, test finale del 13 agosto che indicava il problema risolto, pubblicazione il 20 agosto e un aggiornamento successivo in cui Brave scrive che, a nuovi test, Perplexity non aveva ancora mitigato del tutto quel tipo di attacco. Che cosa valga oggi non lo so. La regola che regge comunque è per chi sviluppa: i contenuti generati dagli utenti sono superficie d'attacco per ogni agente che legge la pagina, e il testo di una pagina non va mai trattato come se fosse un'istruzione del tuo utente.
Primo contatto: installare, autenticarsi, validare una richiesta
Gli SDK ufficiali sono due: pip install perplexityai per Python e npm install @perplexity-ai/perplexity_ai per TypeScript. Entrambi leggono la chiave dalla variabile d'ambiente PERPLEXITY_API_KEY; il quickstart avverte di non stamparla mai, nemmeno in parte, perché finirebbe nella cronologia della shell e nei log. Se non hai ancora una chiave, il lavoro utile da fare subito è un altro: capire la forma delle richieste prima di spendere un centesimo.
Lo script che segue costruisce e valida, senza inviarle, richieste per l'Agent API e per la Search API secondo lo schema documentato. È un controllo mio, scritto dalle pagine che ho letto: non sostituisce il server, che resta l'arbitro (per un livello di effort sconosciuto la documentazione dice che risponde HTTP 400, cosa che qui non ho provato). Serve a due cose: far fallire in locale gli errori banali, e mostrare quali campi appartengono a quale API, un errore frequente quando si passa da una all'altra.
"""Costruisce e valida, senza inviarle, due richieste secondo lo schema documentato."""
import json
import re
EFFORT = {"fast", "low", "medium", "high", "xhigh", "ultra"}
FORMA_EFFORT = re.compile(r"^(?P<livello>[a-z]+)(@(?P<versione>latest|\d{4}-\d{2}-\d{2}\.\d+))?$")
def valida_agent(corpo: dict) -> list[str]:
errori = []
if "effort" in corpo:
m = FORMA_EFFORT.match(str(corpo["effort"]))
if not m or m["livello"] not in EFFORT:
errori.append(f"effort sconosciuto: {corpo['effort']!r}")
if "profile" in corpo:
errori.append("effort e profile non si passano insieme")
elif "model" not in corpo and "models" not in corpo and "profile" not in corpo:
errori.append("serve effort, model, models o profile")
if "input" not in corpo:
errori.append("manca input")
for strumento in corpo.get("tools", []):
if strumento.get("type") == "web_search":
n = strumento.get("max_results")
if n is not None and not 1 <= n <= 50:
errori.append(f"web_search.max_results fuori da 1-50: {n}")
filtro = strumento.get("filters", {}).get("search_domain_filter", [])
if len(filtro) > 20:
errori.append("search_domain_filter: oltre 20 voci")
if any(v.startswith("-") for v in filtro) and not all(v.startswith("-") for v in filtro):
errori.append("search_domain_filter: lista consentita e negata insieme")
return errori
def valida_search(corpo: dict) -> list[str]:
errori = []
q = corpo.get("query")
if isinstance(q, list):
if not 1 <= len(q) <= 5:
errori.append(f"query: da 1 a 5 voci, trovate {len(q)}")
elif not isinstance(q, str) or not q.strip():
errori.append("query assente o vuota")
n = corpo.get("max_results", 10)
if not 1 <= n <= 20:
errori.append(f"max_results fuori da 1-20: {n}")
if corpo.get("search_type", "web") not in {"web", "fast"}:
errori.append("search_type: web o fast")
for campo in ("model", "effort", "instructions", "tools", "max_output_tokens"):
if campo in corpo:
errori.append(f"{campo} e' un campo dell'Agent API, non della Search API")
return errori
PROVE = [
("agent", {"effort": "low", "input": "Che cos'e' il file robots.txt?"}),
("agent", {"effort": "fast@2026-10-16.0", "input": "ciao"}),
("agent", {"effort": "ultra-preview", "input": "ciao"}),
("agent", {"effort": "low", "profile": "mio", "input": "ciao"}),
("agent", {"effort": "low", "input": "x", "tools": [{"type": "web_search", "max_results": 80}]}),
("search", {"query": ["a", "b"], "max_results": 5, "search_type": "fast"}),
("search", {"query": "x", "max_results": 50, "effort": "low"}),
]
for tipo, corpo in PROVE:
errori = (valida_agent if tipo == "agent" else valida_search)(corpo)
esito = "OK" if not errori else "; ".join(errori)
print(f"{tipo:6} {json.dumps(corpo, ensure_ascii=False)} -> {esito}")
# Output:
# agent {"effort": "low", "input": "Che cos'e' il file robots.txt?"} -> OK
# agent {"effort": "fast@2026-10-16.0", "input": "ciao"} -> OK
# agent {"effort": "ultra-preview", "input": "ciao"} -> effort sconosciuto: 'ultra-preview'
# agent {"effort": "low", "profile": "mio", "input": "ciao"} -> effort e profile non si passano insieme
# agent {"effort": "low", "input": "x", "tools": [{"type": "web_search", "max_results": 80}]} -> web_search.max_results fuori da 1-50: 80
# search {"query": ["a", "b"], "max_results": 5, "search_type": "fast"} -> OK
# search {"query": "x", "max_results": 50, "effort": "low"} -> max_results fuori da 1-20: 50; effort e' un campo dell'Agent API, non della Search API
Il codice è stato eseguito due volte con uscita identica (Python 3.14, solo libreria standard). Le righe da guardare sono la terza e l'ultima. ultra-preview è un nome che non compare più fra i livelli documentati (oggi il sesto livello si chiama ultra), e il validatore lo rifiuta: se hai codice scritto su un nome d'anteprima, un controllo così lo trova prima del server. L'ultima richiesta mescola un campo dell'Agent API (effort) in una richiesta di ricerca: la documentazione dice che quei campi non fanno parte di POST /search. Non usarlo come garanzia: se la documentazione cambia, il validatore resta fermo e va aggiornato a mano.
Con una chiave, le due chiamate dei quickstart hanno questa forma. È uno schema da adattare, non eseguito qui:
from perplexity import Perplexity
client = Perplexity() # legge PERPLEXITY_API_KEY dall'ambiente
# Risposta già scritta, con fonti inline (Agent API)
risposta = client.responses.create(effort="low", input="Che cos'è robots.txt?")
print(risposta.output_text)
# Solo le fonti, per la tua pipeline (Search API)
ricerca = client.search.create(query="robots.txt", max_results=5)
for r in ricerca.results:
print(r.title, r.url)
Le due chiamate usano lo stesso oggetto client ma metodi e formati di risposta diversi: responses.create restituisce un oggetto con output_text (e un array output che registra l'esecuzione), search.create un elenco results con titolo, indirizzo e testo estratto. Non c'è nessun modello dietro la seconda: se la risposta la vuoi scritta, la scrive il tuo modello, e di come si controlla ciò che scrive parlano gli articoli 2 e 3.
La chiave API: tre abitudini che costano zero
Il quickstart insiste su un punto che sembra banale e non lo è: la chiave si legge dall'ambiente e non si stampa. Tradotto in pratica, per un servizio vero:
- Una chiave per ambiente (sviluppo, produzione), così una chiave trapelata da un log di sviluppo non apre il consumo reale.
- Mai nel frontend. Un'app Angular o React che chiama
api.perplexity.aidal browser espone la chiave a chiunque apra gli strumenti di rete; la chiamata passa dal tuo backend, che è anche il posto giusto per limitare le richieste per utente. - Un tetto di spesa tuo, a prescindere da quello del fornitore: un contatore di chiamate per giorno nel tuo servizio trasforma un bug con ciclo infinito in un errore invece che in una fattura.
Le tre abitudini valgono per qualunque API a pagamento, non solo per questa; l'ultima è la più trascurata, perché il limite del fornitore protegge il fornitore, non il tuo conto. Nell'articolo 6 il contatore diventa codice. C'è poi un quarto tema, diverso: che cosa mandi nelle query.
Che cosa non deve entrare nelle query
La pagina «Privacy & Security» dice che, secondo le condizioni d'uso dell'API, Perplexity non usa il contenuto dei clienti per addestrare modelli generativi, che la Zero Data Retention non è predefinita (è disponibile solo ai clienti idonei, con configurazione a livello di account e accordo scritto) e che non tutti i modelli la supportano. La pagina elenca poi il rapporto SOC 2 Type II, una valutazione HIPAA del 2025 e il questionario CAIQlite, e rimanda al Trust Center per i sub-responsabili; il GDPR non è nominato e i dati personali sono trattati secondo il Data Processing Addendum. Dove i dati siano conservati o elaborati la pagina non lo dice.
Il punto che sorprende riguarda l'Agent API. La pagina sullo stato della conversazione dice che l'Agent API conserva lato server lo stato delle risposte, per poterle recuperare o continuare con previous_response_id, e che store: false nasconde la risposta dalla lettura ma non disattiva la conservazione; chi ha un accordo ZDR è invitato a sentire il proprio referente prima di usare le funzioni con stato. Un cliente che aveva promesso la ZDR ai propri utenti sulle chat completions lo ha scritto nel forum il 24 agosto 2026 chiedendo come migrare; nel thread non c'è risposta dello staff. Non ne traggo un giudizio sul prodotto ma una regola: prima di spostare un flusso con impegni contrattuali sui dati, chiedi per iscritto se la ZDR copre l'endpoint e i modelli che userai.
A monte, senza aspettare il contratto, puoi fare in modo che i dati personali non entrino nelle query. Questo filtro è un minimo; l'ho eseguito su quattro frasi di prova.
import re
CODICE_FISCALE = re.compile(r"\b[A-Z]{6}\d{2}[A-Z]\d{2}[A-Z]\d{3}[A-Z]\b", re.I)
EMAIL = re.compile(r"\b[\w.+-]+@[\w-]+\.[\w.-]+\b")
def query_sicura(testo: str) -> str:
if CODICE_FISCALE.search(testo) or EMAIL.search(testo):
raise ValueError("La query contiene dati personali: riformulala.")
return testo
PROVE = [
"come funziona il file robots.txt",
"storico ordini di RSSMRA80A01H501U",
"scrivi a mario.rossi@example.org e riassumi",
"Mario Rossi, nato a Lecce, ha il diabete: che cosa cerco?",
]
for p in PROVE:
try:
query_sicura(p)
print("passa :", p)
except ValueError as e:
print("bloccata :", p, "->", e)
# Output:
# passa : come funziona il file robots.txt
# bloccata : storico ordini di RSSMRA80A01H501U -> La query contiene dati personali: riformulala.
# bloccata : scrivi a mario.rossi@example.org e riassumi -> La query contiene dati personali: riformulala.
# passa : Mario Rossi, nato a Lecce, ha il diabete: che cosa cerco?
Le due espressioni regolari riconoscono un codice fiscale (sei lettere, due cifre, una lettera, due cifre, una lettera, tre cifre, una lettera) e un indirizzo email, e query_sicura solleva un errore invece di lasciar passare la query. L'ultima riga dell'uscita è la lezione: un nome, una città e una malattia scritti in prosa passano indisturbati. Il filtro serve a far fallire rumorosamente il caso più banale; per i dati sanitari o giudiziari serve un controllo a monte che decida quali informazioni possono lasciare il tuo sistema, non un'espressione regolare.
L'indice della serie
- Questa mappa.
- Agent API: livelli di effort, risposte e citazioni.
- Search API per una pipeline RAG tua.
- Da Sonar all'Agent API, senza danni.
- Il server MCP ufficiale in Claude Code, Cursor e VS Code.
- Costi, limiti di QPS e gestione dei 429.
- PerplexityBot e Perplexity-User: cosa si controlla con
robots.txt. - Farsi citare: cosa è dimostrato e cosa è congettura.
L'ordine è quello di una decisione: prima scegli l'API (1-3), poi porti il codice esistente (4), poi lo colleghi agli strumenti di sviluppo (5), poi lo fai reggere ai limiti e ai costi (6), infine guardi la faccia opposta, quella di chi pubblica contenuti letti da questi sistemi (7-8). Se arrivi da altre serie del sito, i punti di contatto sono il protocollo MCP (articolo 5) e la configurazione da riga di comando in Claude Code; per i rischi di privacy di un assistente che legge il tuo codice c'è Sicurezza e Privacy con Claude Code.
Che cosa sai fare adesso
Sai distinguere le cinque API e sai dire quale ti serve in base a chi deve controllare il processo. Sai che cosa costa ciascuna, con la sua unità di misura, e dove il costo dell'Agent API ha una parte che non si legge sulla pagina dei prezzi ma nella risposta. Sai che Sonar non è più il punto di partenza, che cosa dice la documentazione sul comportamento delle richieste sincrone e perché una chiave si tiene fuori dal frontend. Hai uno script per validare una richiesta prima di inviarla e uno per tenere i dati personali fuori dalle query. Il passo successivo è l'articolo 2 se vuoi una risposta pronta, il 3 se vuoi le fonti grezze.
Domande frequenti
Quante API ha Perplexity per sviluppatori?
La documentazione ne elenca cinque: Agent API, Search API, Decisions API, Embeddings API e Orchestrator API (quest'ultima in anteprima privata). Condividono una chiave e l'host api.perplexity.ai.
Meglio Agent API o Search API?
Dipende da chi deve controllare il processo. L'Agent API restituisce una risposta già citata ma il costo dipende dal numero di passi; la Search API restituisce solo risultati e ha un costo per richiesta prevedibile, a fronte di più codice tuo.
Posso ancora usare i modelli Sonar?
La documentazione di migrazione letta il 13 novembre 2026 dice che il supporto alle chat completions Sonar è terminato il 27 settembre 2026, che le richieste sincrone e in streaming vengono riformulate come richieste Agent API e che quelle asincrone non sono più supportate.
La Zero Data Retention è attiva di default?
No. La pagina Privacy & Security la descrive come disponibile solo ai clienti idonei, con configurazione a livello di account e accordo scritto, e non supportata da tutti i modelli.
Fonti
- Perplexity, Overview delle API - le cinque API, host, endpoint, modelli di Decisions e Embeddings; consultata il 2026-11-13
- Perplexity, Quickstart - installazione degli SDK, variabile d'ambiente, forma delle chiamate e avvertenza sulla chiave; consultata il 2026-11-13
- Perplexity, Pricing - tariffe degli strumenti, della Search API, degli embeddings e di Decisions; consultata il 2026-11-13
- Perplexity, Agent API Models - tariffe per milione di token di
openai/gpt-6-luna; consultata il 2026-11-13 - Perplexity, Migrate from Sonar to the Agent API - fine del supporto il 27 settembre 2026 e sorte delle richieste sincrone, in streaming e asincrone; consultata il 2026-11-13
- Perplexity, Conversation state - la conservazione lato server dello stato e il comportamento di
store: false; consultata il 2026-11-13 - Perplexity, Privacy & Security - ZDR, uso dei dati, certificazioni e sub-responsabili; consultata il 2026-11-13
- Community Perplexity, Sonar moving to Agents API - la risposta dello staff del 10 settembre 2026 sul ritiro dell'endpoint; letta il 2026-11-13
- Community Perplexity, Zero Data Retention with Agent API - la domanda di un cliente del 24 agosto 2026 (nessuna risposta dello staff nel thread); letta il 2026-11-13
- Brave, Agentic Browser Security: Indirect Prompt Injection in Perplexity Comet - cronologia della segnalazione e descrizione della dimostrazione (fonte di un concorrente, senza revisione indipendente); pubblicata il 2025-08-20, letta il 2026-11-13
Commenti
Caricamento commenti...
Accedi per commentare