Ein Perplexity API-Schlüssel ist das Zugangsmerkmal, das Sie mit jeder Anfrage an api.perplexity.ai senden. Er identifiziert Ihr Projekt, belastet Ihr Prepaid-Guthaben und legt Ihre Ratenbegrenzungsstufe fest. Wenn Sie noch nie einen verwendet haben, deckt unser Einsteigerartikel über was ein API-Schlüssel ist die Grundlagen ab. Dieser Leitfaden behandelt den Perplexity-spezifischen Teil: das Erstellen des Kontos, das Hinzufügen von Guthaben, das Generieren des Schlüssels und das Senden Ihrer ersten fundierten Sonar-Anfrage von curl, Python und Apidog.
Ein Hinweis zum Timing, bevor Sie beginnen. Perplexity hat Sonar auf seine Agent API umgestellt, und der offizielle Quickstart verweist jetzt dorthin. Der alte Sonar Chat-Completions-Endpunkt funktioniert weiterhin bis zum 27. September 2026 und wird dann eingestellt. Jedes Beispiel unten verwendet den aktuellen Endpunkt, mit einem kurzen Hinweis auf die veraltete Form, falls Sie älteren Code warten.
Was Sie vor dem Start benötigen
- Ein Perplexity-Konto. Google, Apple, SSO oder eine passwortlose E-Mail-Anmeldung funktionieren alle und lösen sich unter derselben E-Mail-Adresse zu demselben Konto auf.
- Eine Zahlungskarte. Die API ist Pay-as-you-go ohne Abonnement, aber Anfragen schlagen fehl, sobald Ihr Guthaben auf null sinkt.
- curl oder Python 3.9+ für die erste Anfrage.
- Apidog, wenn Sie den Schlüssel als lokales Geheimnis speichern und die Anfrage als wiederholbaren Test speichern möchten.
Schritt 1: Melden Sie sich bei der API-Konsole an und erstellen Sie ein Projekt
Gehen Sie zu console.perplexity.ai und wählen Sie eine Anmeldemethode. Die Anmeldung erstellt ein Perplexity-Konto, aber kein API-Projekt. Bei Ihrem ersten Besuch fordert Sie der Einrichtungsassistent auf, ein Projekt zu erstellen oder einem beizutreten, bevor Sie einen Schlüssel generieren können, da Schlüssel an Projekte gebunden sind.
Öffnen Sie Einstellungen in der linken Seitenleiste und geben Sie den Namen, die Adresse und die Steuerdaten Ihrer Organisation ein; diese erscheinen auf Ihren Rechnungen. Wenn Ihr Unternehmen bereits ein Projekt hat, bitten Sie einen Administrator, Sie diesem hinzuzufügen, anstatt ein zweites zu erstellen. Separate Projekte erhalten separate Guthaben und Schlüssel, was nützlich ist, um eine Produktionsanwendung von einem Experiment zu isolieren.
Schritt 2: Zahlungsmethode und Guthaben hinzufügen
Öffnen Sie die Abrechnungsseite und fügen Sie eine Karte hinzu. Laut Dokumentation belastet das Hinzufügen einer Zahlungsmethode die Karte nicht; es speichert die Details für die zukünftige Nutzung. Kaufen Sie dann Guthaben. Das Guthaben, die Aufschlüsselung der Nutzung pro Modell und die Rechnungshistorie finden Sie alle auf dieser Seite.
Zwei Details sind hier wichtig. Die API wird aus Prepaid-Guthaben abgerechnet, und wenn das Guthaben aufgebraucht ist, werden Ihre Schlüssel blockiert, bis Sie es aufladen. Die Dokumentation beschreibt diesen Fehler als 401, nicht als 402, sodass eine Anwendung ohne Guthaben auf den ersten Blick wie ein Authentifizierungsfehler aussieht. Und neben Automatisches Aufladen klicken Sie auf Einstellungen ändern, damit die Konsole automatisch Guthaben hinzufügt, wenn der Betrag unter einen von Ihnen festgelegten Schwellenwert fällt. Aktivieren Sie dies, bevor etwas in Produktion geht.
Die Dokumentation veröffentlicht keinen Mindestkaufbetrag, orientieren Sie sich also an dem, was auf der Abrechnungsseite angezeigt wird. Ihre Nutzungsebene, die Ihre Ratenbegrenzungen festlegt, basiert auf dem kumulierten Guthaben, das über die gesamte Lebensdauer des Kontos gekauft wurde, nicht auf dem aktuellen Guthaben.
Schritt 3: API-Schlüssel generieren
Öffnen Sie die API-Schlüssel-Seite in der Konsole und erstellen Sie einen Schlüssel. Geben Sie ihm einen aussagekräftigen Namen wie dev-laptop oder prod-search-worker. Nach der Erstellung ist der Name die einzige Möglichkeit, Schlüssel zu unterscheiden, da der vollständige Wert nur einmal angezeigt und danach nicht mehr abgerufen werden kann. Kopieren Sie ihn sofort.
Speichern Sie den Schlüssel in einer Umgebungsvariable, niemals im Code:
export PERPLEXITY_API_KEY="pplx-ihr-schlüssel-hier"
Verwenden Sie unter Windows setx PERPLEXITY_API_KEY "pplx-ihr-schlüssel-hier" und öffnen Sie ein neues Terminal.
Sie können innerhalb eines Projekts mehrere Schlüssel erstellen, erstellen Sie also einen pro Umgebung und pro Dienst. Das Widerrufen eines Schlüssels ist dauerhaft, was Sie wünschen, wenn ein Schlüssel geleakt ist. Wenn Sie sich nicht sicher sind, ob ein Schlüssel bereits in ein Repository gelangt ist, führen Sie einen Secret Scanner über Ihre Git-Historie aus, bevor Sie ihn rotieren.
Schritt 4: Ihre erste Sonar-Anfrage senden
Der aktuelle Endpunkt ist POST https://api.perplexity.ai/v1/agent. Die Authentifizierung erfolgt über einen Standard-Bearer-Header, Authorization: Bearer $PERPLEXITY_API_KEY. Der Body nimmt eine model und einen input-String entgegen. Die Sonar-Modell-ID an diesem Endpunkt ist perplexity/sonar, und das Hinzufügen des web_search-Tools weist es an, das Live-Web zu durchsuchen und Quellen anzuhängen.
Fragen Sie es etwas mit einer echten Antwort, die sich im Laufe der Zeit ändert:
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "perplexity/sonar",
"input": "Welche Node.js Release-Reihe ist derzeit Active LTS, und wann erreicht sie das End of Life?",
"tools": [{ "type": "web_search" }]
}' | jq
Die Antwort enthält output_text, die Antwort als Klartext, und ein output-Array mit einem Element pro Schritt, den das Modell ausgeführt hat. Das message-Element enthält die Antwort; das search_results-Element listet die gelesenen Seiten auf, jede mit einer url, title, snippet und date. Das usage-Objekt meldet Token-Zahlen und Kosten. Ein status von completed bedeutet, dass der Lauf abgeschlossen ist.
Die gleiche Anfrage in Python mit dem offiziellen SDK:
pip install perplexityai
from perplexity import Perplexity
client = Perplexity() # liest PERPLEXITY_API_KEY aus der Umgebung
response = client.responses.create(
model="perplexity/sonar",
input="Welche Node.js Release-Reihe ist derzeit Active LTS, und wann erreicht sie das End of Life?",
tools=[{"type": "web_search"}],
)
print(response.output_text)
Wenn Sie das OpenAI SDK bevorzugen, setzen Sie base_url="https://api.perplexity.ai/v1" und rufen Sie client.responses.create() mit denselben Argumenten auf. Das SDK leitet es an /v1/responses weiter, was Perplexity als Alias akzeptiert. Voreinstellungen (fast, low, medium, high, xhigh) bündeln ein Modell, Token-Budgets und Tools für Sie; im OpenAI SDK übergeben Sie diese über extra_body.
Wenn Sie die veraltete Chat-Completions-Form verwenden
Älterer Code sendet messages an https://api.perplexity.ai/v1/sonar mit den Modell-IDs sonar, sonar-pro, sonar-reasoning-pro oder sonar-deep-research und liest choices[0].message.content. Diese Form funktioniert bis zum 27. September 2026. Der Migrationsleitfaden ordnet sonar zu perplexity/sonar, sonar-pro zu perplexity/sonar mit der Voreinstellung low und Deep Research zu der Voreinstellung high zu. Die Optionen search_domain_filter und search_recency_filter werden als filters-Objekt innerhalb des web_search-Tools verschoben.
Schritt 5: Schlüssel speichern und Anfrage in Apidog sichern
Ein einmal funktionierender Curl-Befehl ist kein Test. Hier ist die Einrichtung, die wir in Apidog verwenden, damit der Schlüssel nicht in der Cloud landet und die Anfrage bei Bedarf ausgeführt wird.
Eine Umgebung erstellen. Fügen Sie eine Umgebung namens Perplexity mit zwei Variablen hinzu: base_url auf https://api.perplexity.ai als gemeinsamen Wert, und PERPLEXITY_API_KEY mit dem gemeinsamen Wert als Platzhalter und dem echten Schlüssel nur im lokalen Wert. Lokale Werte leben im Cache Ihres Clients und werden niemals mit Teamkollegen synchronisiert, was der ganze Sinn ist. Unser Leitfaden zu Umgebungen und geheimen Variablen in Apidog geht tiefer auf die Aufteilung zwischen gemeinsam und lokal ein.
Die Anfrage erstellen. Neue Anfrage, POST {{base_url}}/v1/agent. Fügen Sie einen Header Authorization: Bearer {{PERPLEXITY_API_KEY}} hinzu, setzen Sie den Body-Typ auf JSON und fügen Sie denselben Body wie im obigen Curl-Befehl ein. Wählen Sie die Umgebung Perplexity und klicken Sie auf Senden. Sie sollten den output_text und den search_results-Block im Antwortbereich sehen.
In einen Test umwandeln. Fügen Sie drei Assertions hinzu: Der Statuscode ist 200, $.status ist gleich completed und $.output_text ist nicht leer. Speichern Sie die Anfrage in einem Testszenario. Jetzt kann jeder im Team das Projekt abrufen, seinen eigenen Schlüssel in den lokalen Wert einfügen und seine Einrichtung mit einem Klick überprüfen. Das Rotieren des Schlüssels bedeutet das Bearbeiten eines Feldes, nicht das Durchsuchen von Skripten.
Wenn Sie es noch nicht haben, laden Sie Apidog kostenlos herunter; der kostenlose Plan deckt vier Benutzer ab, genug für ein kleines Team, um das Projekt zu teilen.
Ratenbegrenzungen und was eine Anfrage kostet
Die Ratenbegrenzungen der Agent API skalieren mit Ihrer Nutzungsebene, und die Ebenen werden durch lebenslange Gutschriftkäufe festgelegt, gemäß der Seite für Ratenbegrenzungen:
| Stufe | Gekaufte Gutschriften | Anfragen pro Sekunde | Anfragen pro Minute |
|---|---|---|---|
| 0 | $0 | 1 | 50 |
| 1 | $50+ | 3 | 150 |
| 2 | $250+ | 8 | 500 |
| 3 | $500+ | 17 | 1.000 |
| 4 | $1.000+ | 33 | 4.000 |
| 5 | $5.000+ | 33 | 8.000 |
Die Begrenzungen verwenden einen Leaky-Bucket-Algorithmus, sodass kurze Anstieg bis zum Limit durchgelassen werden. Wenn Sie es überschreiten, gibt die API einen 429 mit einem Retry-After-Header zurück, und abgelehnte Anfragen werden nicht abgerechnet. Ihre aktuelle Stufe wird auf der Preisseite der Konsole unter dem Tab "Nutzungsebenen" angezeigt.
Zum Preis: Ein Absatz reicht hier aus. Die Preisseite listet perplexity/sonar auf der Agent API mit 0,25 $ pro Million Eingabe-Tokens und 2,50 $ pro Million Ausgabe-Tokens auf, plus 0,0025 $ pro web_search-Aufruf. Die älteren Sonar Chat-Completions-Modelle werden anders abgerechnet: sonar mit 1 $ pro Million Tokens (Ein- und Ausgabe), plus 5 $ bis 12 $ pro tausend Anfragen, abhängig von der Größe des Suchkontexts. Eine vollständige Aufschlüsselung und den Pro-Konto-Aspekt finden Sie in unserem Perplexity API-Leitfaden.
Häufige Fehler und wie man sie behebt
401 Unauthorized. Drei Ursachen, in der Reihenfolge der Wahrscheinlichkeit: Der Header ist falsch (er muss Authorization: Bearer <key> sein, und die Shell-Variable muss im selben Terminal exportiert werden), der Schlüssel wurde widerrufen oder das Guthaben ist auf null. Überprüfen Sie die Abrechnungsseite, bevor Sie etwas neu generieren. Das Python SDK löst hierfür AuthenticationError aus.
400 Bad Request. Normalerweise ein Body im alten Format, der an den neuen Endpunkt gesendet wird: messages anstelle von input, oder eine einfache sonar-pro Modell-ID an /v1/agent. Das SDK meldet dies als ValidationError.
404 Not Found. Der Pfad ist falsch. /v1/agent ist die Agent API und /v1/sonar ist der veraltete Chat-Completions-Endpunkt; die Dokumentation listet nichts anderes auf.
429 Too Many Requests. Sie haben das Limit Ihrer Stufe erreicht. Lesen Sie Retry-After, warten Sie so lange und versuchen Sie es dann mit exponentiellem Backoff und Jitter erneut. Der Kauf von Guthaben erhöht Ihre Stufe, wenn Sie einen konstanten Durchsatz benötigen. Der Fehlerbehandlungsleitfaden des SDK zeigt das RateLimitError-Muster.
500 oder 503. Serverseitig. Versuchen Sie es mit einer Verzögerung erneut; enge Wiederholungsschleifen verschlimmern die Ratenbegrenzung.
FAQ
Gibt es einen kostenlosen Perplexity API-Schlüssel?
Es ist kein kostenloser Tarif dokumentiert. Die API ist Pay-as-you-go von einem Prepaid-Guthaben, und ein Projekt ohne Guthaben wird blockiert. Die Kosten für eine erste Anfrage mit perplexity/sonar und einer Websuche betragen einen Bruchteil eines Cents, sodass eine kleine Aufladung viele Tests abdeckt.
Welche Modell-ID sollte ich für eine erste Anfrage verwenden?
Verwenden Sie perplexity/sonar auf /v1/agent mit dem web_search-Tool. Es ist die kostengünstigste, fundierte Option und diejenige, auf die der Migrationsleitfaden die alten sonar- und sonar-pro-IDs abbildet. Wechseln Sie zu einer Voreinstellung wie low oder medium, wenn Sie möchten, dass Perplexity das Modell und das Suchbudget für Sie auswählt.
Brauche ich die Agent API, wenn ich nur Suchergebnisse möchte?
Nein. Die separate Search API liefert gerankte Ergebnisse ohne ein Modell auszuführen, was günstiger ist, wenn Sie Seiten in Ihre eigene Pipeline einspeisen. Unser Walkthrough der Perplexity Search API zeigt die Anfrageform und Filter.
Wie rotiere ich einen Schlüssel ohne Ausfallzeiten?
Erstellen Sie einen zweiten Schlüssel im selben Projekt, stellen Sie ihn überall dort bereit, wo der alte verwendet wurde, bestätigen Sie den Datenverkehr mit dem neuen Schlüssel und widerrufen Sie dann den alten. Der Widerruf ist dauerhaft, aktualisieren Sie daher zuerst jeden Consumer. Perplexity stellt auch Endpunkte /generate_auth_token und /revoke_auth_token bereit, wenn Sie die Rotation skripten möchten.
Zusammenfassung
Melden Sie sich an, erstellen Sie ein Projekt, kaufen Sie Guthaben, generieren Sie einen Schlüssel, senden Sie eine Anfrage an /v1/agent mit perplexity/sonar. Das ist der ganze Weg. Speichern Sie den Schlüssel als lokalen Wert in Apidog und die Anfrage als Test, und die nächste Person in Ihrem Team erhält in wenigen Minuten eine überprüfbare Einrichtung. Wenn Sie noch Code am Chat-Completions-Endpunkt haben, migrieren Sie ihn vor dem 27. September 2026.