Cara Mendapatkan Kunci API Perplexity dan Melakukan Permintaan Sonar Pertama Anda

Kunci API Perplexity adalah kredensial yang Anda kirim dengan setiap permintaan ke api.perplexity.ai. Kunci ini mengidentifikasi proyek Anda, mengurangi saldo kredit prabayar Anda, dan menentukan tingkat batas tarif Anda. Jika Anda belum pernah menggunakannya, panduan kami tentang apa itu kunci API mencakup dasar-dasarnya. Panduan ini mencakup bagian khusus Perplexity: membuat akun, menambahkan kredit, menghasilkan kunci, dan mengirim permintaan Sonar tergrounded pertama Anda dari curl, Python, dan Apidog.

Satu catatan waktu sebelum Anda memulai. Perplexity memindahkan Sonar ke Agent API-nya, dan panduan singkat resmi sekarang menunjuk ke sana. Endpoint `chat-completions` Sonar yang lama akan tetap berfungsi hingga 27 September 2026, lalu akan dinonaktifkan. Setiap contoh di bawah ini menggunakan endpoint saat ini, dengan catatan singkat tentang bentuk lama jika Anda mempertahankan kode lama.

button

Yang Anda perlukan sebelum memulai

Akun Perplexity. Google, Apple, SSO, atau pendaftaran email tanpa kata sandi semuanya berfungsi, dan semuanya terhubung ke akun yang sama berdasarkan alamat email.
Kartu pembayaran. API bersifat bayar-sesuai-penggunaan tanpa langganan, tetapi permintaan akan gagal setelah saldo kredit Anda mencapai nol.
curl atau Python 3.9+ untuk permintaan pertama.
Apidog jika Anda ingin kunci disimpan sebagai rahasia lokal dan permintaan disimpan sebagai pengujian yang dapat diulang.

Langkah 1: Masuk ke konsol API dan buat proyek

Buka console.perplexity.ai dan pilih metode masuk. Masuk akan membuat akun Perplexity, tetapi bukan proyek API. Pada kunjungan pertama Anda, wizard pengaturan akan meminta Anda untuk membuat atau bergabung dengan proyek sebelum Anda dapat menghasilkan kunci, karena kunci dicakupkan ke proyek.

Buka Settings di sidebar kiri dan isi nama, alamat, dan detail pajak organisasi Anda; informasi ini akan muncul di faktur Anda. Jika perusahaan Anda sudah memiliki proyek, minta admin untuk menambahkan Anda ke proyek tersebut daripada membuat proyek kedua. Proyek terpisah mendapatkan saldo kredit dan kunci terpisah, yang berguna untuk mengisolasi aplikasi produksi dari eksperimen.

Langkah 2: Tambahkan metode pembayaran dan kredit

Buka halaman Penagihan dan tambahkan kartu. Sesuai dokumen, menambahkan metode pembayaran tidak akan mengenakan biaya pada kartu; ini menyimpan detail untuk penggunaan di masa mendatang. Kemudian beli kredit. Saldo, rincian penggunaan per model, dan riwayat faktur semuanya ada di halaman ini.

Dua detail penting di sini. API mengenakan biaya dari kredit prabayar, dan jika saldo habis, kunci Anda akan diblokir sampai Anda mengisi ulang. Dokumen menjelaskan kegagalan itu sebagai 401, bukan 402, jadi aplikasi kehabisan kredit terlihat seperti bug otentikasi pada pandangan pertama. Dan di samping Auto reload, klik Change preferences untuk meminta konsol menambahkan kredit secara otomatis ketika saldo turun di bawah ambang batas yang Anda tetapkan. Aktifkan itu sebelum apa pun masuk ke produksi.

Dokumen tidak mempublikasikan jumlah pembelian minimum, jadi ikuti apa yang ditampilkan halaman penagihan. Tingkat penggunaan Anda, yang menetapkan batas tarif Anda, didasarkan pada akumulasi kredit yang dibeli sepanjang masa akun, bukan pada saldo saat ini.

Langkah 3: Hasilkan kunci API

Buka halaman Kunci API di konsol dan buat kunci. Beri nama deskriptif seperti dev-laptop atau prod-search-worker. Setelah dibuat, nama adalah satu-satunya cara untuk membedakan kunci, karena nilai lengkap hanya ditampilkan sekali dan tidak dapat diambil kembali. Salin segera.

Letakkan kunci dalam variabel lingkungan, jangan pernah dalam kode:

export PERPLEXITY_API_KEY="pplx-your-key-here"

Di Windows, gunakan setx PERPLEXITY_API_KEY "pplx-your-key-here" dan buka terminal baru.

Anda dapat membuat beberapa kunci dalam satu proyek, jadi buat satu per lingkungan dan per layanan. Mencabut kunci bersifat permanen, itulah yang Anda inginkan ketika kunci bocor. Jika Anda tidak yakin apakah kunci sudah bocor ke repositori, jalankan pemindai rahasia melalui riwayat git Anda sebelum Anda merotasi.

Langkah 4: Lakukan permintaan Sonar pertama Anda

Endpoint saat ini adalah POST https://api.perplexity.ai/v1/agent. Otentikasi adalah header bearer standar, Authorization: Bearer $PERPLEXITY_API_KEY. Body mengambil string model dan input. ID model Sonar pada endpoint ini adalah perplexity/sonar, dan menambahkan alat web_search memberitahunya untuk mencari web langsung dan melampirkan sumber.

Tanyakan sesuatu dengan jawaban nyata yang berubah seiring waktu:

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "perplexity/sonar",
    "input": "Which Node.js release line is currently Active LTS, and when does it reach end of life?",
    "tools": [{ "type": "web_search" }]
  }' | jq

Respon membawa output_text, jawaban sebagai teks biasa, dan array output dengan satu item per langkah yang diambil model. Item message berisi jawaban; item search_results mencantumkan halaman yang dibaca, masing-masing dengan url, title, snippet, dan date. Objek usage melaporkan jumlah token dan biaya. status completed berarti proses telah selesai.

Permintaan yang sama dalam Python dengan SDK resmi:

pip install perplexityai

from perplexity import Perplexity

client = Perplexity()  # membaca PERPLEXITY_API_KEY dari lingkungan

response = client.responses.create(
    model="perplexity/sonar",
    input="Which Node.js release line is currently Active LTS, and when does it reach end of life?",
    tools=[{"type": "web_search"}],
)

print(response.output_text)

Jika Anda lebih suka OpenAI SDK, atur base_url="https://api.perplexity.ai/v1" dan panggil client.responses.create() dengan argumen yang sama. SDK mengarahkannya ke /v1/responses, yang diterima Perplexity sebagai alias. Preset (fast, low, medium, high, xhigh) menggabungkan model, anggaran token, dan alat untuk Anda; pada OpenAI SDK Anda meneruskannya melalui extra_body.

Jika Anda menggunakan bentuk chat-completions lama

Kode lama mengirim messages ke https://api.perplexity.ai/v1/sonar dengan ID model sonar, sonar-pro, sonar-reasoning-pro, atau sonar-deep-research, dan membaca choices[0].message.content. Bentuk tersebut berfungsi hingga 27 September 2026. Panduan migrasi memetakan sonar ke perplexity/sonar, sonar-pro ke perplexity/sonar dengan preset low, dan penelitian mendalam ke preset high. Opsi search_domain_filter dan search_recency_filter berpindah ke dalam alat web_search sebagai objek filters.

Langkah 5: Simpan kunci dan simpan permintaan di Apidog

Curl yang hanya berfungsi sekali bukanlah sebuah pengujian. Berikut adalah pengaturan yang kami gunakan di Apidog agar kunci tetap di luar cloud dan permintaan dapat dijalankan sesuai permintaan.

Buat lingkungan. Tambahkan lingkungan bernama Perplexity dengan dua variabel: base_url diatur ke https://api.perplexity.ai sebagai nilai bersama, dan PERPLEXITY_API_KEY dengan nilai bersama dibiarkan sebagai placeholder dan kunci asli hanya di nilai lokal. Nilai lokal berada di cache klien Anda dan tidak pernah disinkronkan dengan rekan tim, itulah intinya. Panduan kami tentang lingkungan dan variabel rahasia di Apidog membahas lebih dalam tentang pembagian nilai bersama-versus-lokal.

Buat permintaan. Permintaan baru, POST {{base_url}}/v1/agent. Tambahkan header Authorization: Bearer {{PERPLEXITY_API_KEY}}, atur jenis body ke JSON, dan tempelkan body yang sama dengan curl di atas. Pilih lingkungan Perplexity dan klik Kirim. Anda akan melihat output_text dan blok search_results di panel respons.

Ubah menjadi pengujian. Tambahkan tiga assertion: kode status adalah 200, $.status sama dengan completed, dan $.output_text tidak kosong. Simpan permintaan ke dalam skenario pengujian. Sekarang siapa pun di tim dapat menarik proyek, menempelkan kunci mereka sendiri ke dalam nilai lokal, dan memverifikasi pengaturan mereka dalam satu klik. Merotasi kunci berarti mengedit satu bidang, bukan mencari di antara skrip.

Jika Anda belum memilikinya, Unduh Apidog secara gratis; paket gratis mencakup empat pengguna, cukup untuk tim kecil untuk berbagi proyek.

Batas tarif dan berapa biaya permintaan

Batas tarif pada Agent API berskala dengan tingkat penggunaan Anda, dan tingkat ditetapkan oleh pembelian kredit seumur hidup, sesuai dengan halaman batas tarif:

Tingkat	Kredit yang dibeli	Permintaan per detik	Permintaan per menit
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

Batas menggunakan algoritma `leaky-bucket`, sehingga semburan singkat hingga batas akan lolos. Ketika Anda melebihi batas, API mengembalikan `429` dengan header `Retry-After`, dan permintaan yang ditolak tidak ditagih. Tingkat Anda saat ini ditampilkan di halaman Harga konsol di bawah tab tingkat penggunaan.

Mengenai harga, satu paragraf sudah cukup di sini. Halaman harga mencantumkan perplexity/sonar di Agent API seharga $0,25 per juta token input dan $2,50 per juta token output, ditambah $0,0025 per pemanggilan web_search. Model `chat-completions` Sonar yang lama ditagih berbeda: sonar seharga $1 per juta token masuk dan keluar, ditambah $5 hingga $12 per seribu permintaan tergantung pada ukuran konteks pencarian. Untuk rincian lengkap dan sudut pandang akun Pro, lihat panduan API Perplexity kami.

Kesalahan umum dan cara memperbaikinya

401 Unauthorized. Tiga penyebab, berdasarkan kemungkinan: header salah (harus Authorization: Bearer <key>, dan variabel shell harus diekspor di terminal yang sama), kunci telah dicabut, atau saldo kredit nol. Periksa halaman penagihan sebelum Anda membuat ulang apa pun. Python SDK menampilkan AuthenticationError untuk ini.

400 Bad Request. Biasanya body dari format lama yang dikirim ke endpoint baru: messages alih-alih input, atau ID model sonar-pro polos pada /v1/agent. SDK menampilkan ini sebagai ValidationError.

404 Not Found. Path salah. /v1/agent adalah Agent API dan /v1/sonar adalah endpoint `chat-completions` lama; dokumen tidak mencantumkan yang lain.

429 Too Many Requests. Anda mencapai batas tingkat Anda. Baca Retry-After, tunggu selama itu, lalu coba lagi dengan `exponential backoff` dan `jitter`. Membeli kredit meningkatkan tingkat Anda jika Anda memerlukan throughput berkelanjutan. Panduan penanganan kesalahan SDK menunjukkan pola RateLimitError.

500 atau 503. Sisi server. Coba lagi dengan jeda; loop `retry` yang ketat memperburuk pembatasan tarif.

FAQ

Apakah ada kunci API Perplexity gratis?

Tidak ada tingkatan gratis yang didokumentasikan. API adalah `pay-as-you-go` dari saldo kredit prabayar, dan proyek tanpa kredit akan diblokir. Biaya permintaan pertama dengan `perplexity/sonar` dan satu pencarian web adalah sebagian kecil dari satu sen, jadi sedikit top-up mencakup banyak pengujian.

ID model mana yang harus saya gunakan untuk permintaan pertama?

Gunakan perplexity/sonar pada /v1/agent dengan alat web_search. Ini adalah opsi tergrounded dengan biaya terendah dan yang dipetakan oleh panduan migrasi untuk ID sonar dan sonar-pro yang lama. Beralih ke preset seperti low atau medium ketika Anda ingin Perplexity memilih model dan anggaran pencarian untuk Anda.

Apakah saya memerlukan Agent API jika saya hanya ingin hasil pencarian?

Tidak. Search API yang terpisah mengembalikan hasil yang telah diberi peringkat tanpa menjalankan model, yang lebih murah saat Anda memasukkan halaman ke dalam pipeline Anda sendiri. Panduan kami tentang Perplexity Search API menunjukkan bentuk permintaan dan filter.

Bagaimana cara merotasi kunci tanpa `downtime`?

Buat kunci kedua di proyek yang sama, terapkan di mana pun kunci lama digunakan, konfirmasikan lalu lintas pada kunci baru, lalu cabut kunci lama. Pencabutan bersifat permanen, jadi perbarui setiap konsumen terlebih dahulu. Perplexity juga mengekspos endpoint /generate_auth_token dan /revoke_auth_token jika Anda ingin membuat skrip rotasi.

Ringkasan

Masuk, buat proyek, beli kredit, hasilkan kunci, kirim satu permintaan ke /v1/agent dengan perplexity/sonar. Itulah keseluruhan jalurnya. Simpan kunci sebagai nilai lokal di Apidog dan simpan permintaan sebagai pengujian, dan orang berikutnya di tim Anda akan mendapatkan pengaturan yang dapat diverifikasi dalam beberapa menit. Jika Anda masih memiliki kode pada endpoint `chat-completions`, migrasikan sebelum 27 September 2026.