Perplexity AI is a Python module that leverages Emailnator to generate new accounts for unlimited pro queries. It supports both synchronous and asynchronous APIs, as well as a web interface for users who prefer a GUI-based approach.
- Account Generation: Automatically generate Gmail accounts using Emailnator
- Unlimited Pro Queries: Bypass query limits by creating new accounts
- Web Interface: Automate account creation and usage via a browser
- Sync & Async APIs: Full support for both synchronous and asynchronous programming
- Type Safety: Complete type hints for better IDE support
- Robust Error Handling: Custom exceptions for better error management
- Comprehensive Logging: Structured logging for debugging
- File Upload: Support for document analysis and Q&A
- Streaming Responses: Real-time response streaming
- Retry Logic: Automatic retry with exponential backoff
- Rate Limiting: Built-in rate limiting to prevent abuse
pip install -e .pip install -e ".[driver]"
patchright install chromiumpip install -e ".[dev]"This includes testing tools (pytest, pytest-cov, pytest-asyncio), linting (flake8, black, isort, mypy), and all optional dependencies.
import perplexity
# Create client
client = perplexity.Client()
# Make a query
response = client.search("What is artificial intelligence?")
print(response['answer'])import perplexity
# Your Perplexity cookies
cookies = {
'next-auth.csrf-token': 'your-token',
'next-auth.session-token': 'your-session',
}
client = perplexity.Client(cookies)
# Use enhanced modes
response = client.search(
"Complex query here",
mode='pro',
model='gpt-4.5',
sources=['scholar']
)for chunk in client.search("Explain quantum computing", stream=True):
if 'answer' in chunk:
print(chunk['answer'], end='', flush=True)import asyncio
import perplexity_async
async def main():
client = await perplexity_async.Client()
response = await client.search("What is machine learning?")
print(response['answer'])
asyncio.run(main())- Examples - Practical examples for common use cases
- Changelog - Bug fixes and changes history
- Improvements - Suggested improvements and roadmap
- API Reference - Complete API documentation
The web interface automates account creation and usage in a browser. Patchright uses "Chrome User Data Directory" to be completely undetected, it's C:\Users\YourName\AppData\Local\Google\Chrome\User Data for Windows, as shown below:
import os
from perplexity.driver import Driver
cli = Driver()
cli.run(rf'C:\\Users\\{os.getlogin()}\\AppData\\Local\\Google\\Chrome\\User Data')To use your own Chrome instance, enable remote debugging (it may enter dead loop in Cloudflare):
- Add
--remote-debugging-port=9222to Chrome's shortcut target. - Pass the port to the
Driver.run()method:
cli.run(rf'C:\\Users\\{os.getlogin()}\\AppData\\Local\\Google\\Chrome\\User Data', port=9222)Below is an example code for simple usage, without using your own account or generating new accounts.
import perplexity
perplexity_cli = perplexity.Client()
# model = model for mode, which can only be used in own accounts, that is {
# 'auto': [None],
# 'pro': [None, 'sonar', 'gpt-5.1', 'claude-4.5-sonnet', 'gemini-2.5-pro', 'grok-4'],
# 'reasoning': [None, 'gpt-5.1-thingking', 'claude-4.5-sonnet-thinking', 'gemini-3.0-pro', 'kimi-k2-thinking'],
# 'deep research': [None]
# }
# sources = ['web', 'scholar', 'social']
# files = a dictionary which has keys as filenames and values as file data
# stream = returns a generator when enabled and just final response when disabled
# language = ISO 639 code of language you want to use
# follow_up = last query info for follow-up queries, you can directly pass response from a query, look at second example below
# incognito = Enables incognito mode, for people who are using their own account
resp = perplexity_cli.search('Your query here', mode='auto', model=None, sources=['web'], files={}, stream=False, language='en-US', follow_up=None, incognito=False)
print(resp)
# second example to show how to use follow-up queries and stream response
for i in perplexity_cli.search('Your query here', stream=True, follow_up=resp):
print(i)And this is how you use your own account, you need to get your cookies in order to use your own account. Look at How To Get Cookies,
import perplexity
perplexity_cookies = {
<your cookies here>
}
perplexity_cli = perplexity.Client(perplexity_cookies)
resp = perplexity_cli.search('Your query here', mode='reasoning', model='o3', sources=['web'], files={'myfile.txt': open('file.txt').read()}, stream=False, language='en-US', follow_up=None, incognito=False)
print(resp)And finally account generating, you need to get cookies for Emailnator to use this feature. Look at How To Get Cookies,
import perplexity
emailnator_cookies = {
<your cookies here>
}
perplexity_cli = perplexity.Client()
perplexity_cli.create_account(emailnator_cookies) # Creates a new gmail, so your 5 pro queries will be renewed.
resp = perplexity_cli.search('Your query here', mode='reasoning', model=None, sources=['web'], files={'myfile.txt': open('file.txt').read()}, stream=False, language='en-US', follow_up=None, incognito=False)
print(resp)Below is an example code for simple usage, without using your own account or generating new accounts.
import asyncio
import perplexity_async
async def test():
perplexity_cli = await perplexity_async.Client()
# mode = ['auto', 'pro', 'reasoning', 'deep research']
# model = model for mode, which can only be used in own accounts, that is {
# 'auto': [None],
# 'pro': [None, 'sonar', 'gpt-5.1', 'claude-4.5-sonnet', 'gemini-2.5-pro', 'grok-4'],
# 'reasoning': [None, 'gpt-5.1-thingking', 'claude-4.5-sonnet-thinking', 'gemini-3.0-pro', 'kimi-k2-thinking'],
# 'deep research': [None]
# }
# sources = ['web', 'scholar', 'social']
# files = a dictionary which has keys as filenames and values as file data
# stream = returns a generator when enabled and just final response when disabled
# language = ISO 639 code of language you want to use
# follow_up = last query info for follow-up queries, you can directly pass response from a query, look at second example below
# incognito = Enables incognito mode, for people who are using their own account
resp = await perplexity_cli.search('Your query here', mode='auto', model=None, sources=['web'], files={}, stream=False, language='en-US', follow_up=None, incognito=False)
print(resp)
# second example to show how to use follow-up queries and stream response
async for i in await perplexity_cli.search('Your query here', stream=True, follow_up=resp):
print(i)
asyncio.run(test())And this is how you use your own account, you need to get your cookies in order to use your own account. Look at How To Get Cookies,
import asyncio
import perplexity_async
perplexity_cookies = {
<your cookies here>
}
async def test():
perplexity_cli = await perplexity_async.Client(perplexity_cookies)
resp = await perplexity_cli.search('Your query here', mode='reasoning', model='o3', sources=['web'], files={'myfile.txt': open('file.txt').read()}, stream=False, language='en-US', follow_up=None, incognito=False)
print(resp)
asyncio.run(test())And finally account generating, you need to get cookies for emailnator to use this feature. Look at How To Get Cookies,
import asyncio
import perplexity_async
emailnator_cookies = {
<your cookies here>
}
async def test():
perplexity_cli = await perplexity_async.Client()
await perplexity_cli.create_account(emailnator_cookies) # Creates a new gmail, so your 5 pro queries will be renewed.
resp = await perplexity_cli.search('Your query here', mode='reasoning', model=None, sources=['web'], files={'myfile.txt': open('file.txt').read()}, stream=False, language='en-US', follow_up=None, incognito=False)
print(resp)
asyncio.run(test())- Open Perplexity.ai website and login to your account.
- Click F12 or
Ctrl + Shift + Ito open inspector. - Go to the "Network" tab in the inspector.
- Refresh the page, right click the first request, hover on "Copy" and click to "Copy as cURL (bash)".
- Now go to the CurlConverter and paste your code here. The cookies dictionary will appear, copy and use it in your codes.
- Open Emailnator website and verify you're human.
- Click F12 or
Ctrl + Shift + Ito open inspector. - Go to the "Network" tab in the inspector.
- Refresh the page, right click the first request, hover on "Copy" and click to "Copy as cURL (bash)".
- Now go to the CurlConverter and paste your code here. The cookies dictionary will appear, copy and use it in your codes.
- Cookies for Emailnator are temporary, you need to renew them continuously.
class Client:
def __init__(self, cookies: Optional[Dict[str, str]] = None):
"""
Initialize Perplexity client.
Args:
cookies: Optional Perplexity account cookies for enhanced features
"""
def search(
self,
query: str,
mode: str = 'auto',
model: Optional[str] = None,
sources: List[str] = ['web'],
files: Dict[str, Union[str, bytes]] = {},
stream: bool = False,
language: str = 'en-US',
follow_up: Optional[Dict] = None,
incognito: bool = False
) -> Union[Dict, Generator]:
"""
Search with Perplexity AI.
Args:
query: Search query
mode: Search mode ('auto', 'pro', 'reasoning', 'deep research')
model: Model to use (depends on mode)
sources: Information sources (['web', 'scholar', 'social'])
files: Files to upload {filename: content}
stream: Enable streaming responses
language: ISO 639 language code
follow_up: Previous query for context
incognito: Enable incognito mode
Returns:
Response dict with 'answer' key, or generator if stream=True
"""
def create_account(self, emailnator_cookies: Dict[str, str]):
"""
Create new account using Emailnator.
Args:
emailnator_cookies: Emailnator cookies for account creation
"""{
'auto': [None],
'pro': [None, 'sonar', 'gpt-5.1', 'claude-4.5-sonnet', 'gemini-2.5-pro', 'grok-4'],
'reasoning': [None, 'gpt-5.1-thinking', 'claude-4.5-sonnet-thinking', 'gemini-3.0-pro', 'kimi-k2-thinking'],
'deep research': [None]
}from perplexity.exceptions import (
PerplexityError, # Base exception
AuthenticationError, # Authentication failed
RateLimitError, # Rate limit exceeded
NetworkError, # Network issues
ValidationError, # Invalid parameters
ResponseParseError, # Failed to parse response
AccountCreationError, # Account creation failed
FileUploadError, # File upload failed
)pytest tests/ -vpytest tests/ --cov=perplexity --cov=perplexity_async --cov-report=htmlpytest tests/test_utils.py -v
pytest tests/test_config.py -v# Clone repository
git clone https://github.com/yourusername/perplexity-ai.git
cd perplexity-ai
# Install in development mode
pip install -e ".[dev]"
# Run tests
pytest
# Format code
black perplexity perplexity_async
# Check types
mypy perplexity perplexity_async
# Lint
flake8 perplexity perplexity_async- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests and linting
- Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Issue: Response returns None
- Solution: The API structure may have changed. Check Changelog for updates.
Issue: Account creation fails
- Solution: Emailnator cookies expire frequently. Get fresh cookies from Emailnator.com.
Issue: File upload fails
- Solution: Ensure you have a valid Perplexity account with file upload quota available.
Issue: Rate limiting
- Solution: Use built-in rate limiting or wait between requests. Consider using async API for better concurrency.
- Check the examples/ directory for working code
- Read the documentation
- Open an issue on GitHub
See CHANGELOG.md for detailed changes and bug fixes.
See IMPROVEMENTS.md for planned improvements and features.
This project is licensed under the MIT License. See the LICENSE file for details.
- Perplexity.ai for the amazing AI search engine
- Emailnator for temporary email service
- All contributors who help improve this project
This is an unofficial API wrapper. Use responsibly and respect Perplexity.ai's terms of service. This project is for educational purposes only.
