1. Installation

pip install --upgrade openperplex

2. API Key Setup

  1. Sign in to Openperplex API Platform

  2. Copy your API Key from the Api Keys Page

3. Instantiate Client

For synchronous usage:

from openperplex import OpenperplexSync

api_key = "your_api_key"
client_sync = OpenperplexSync(api_key)

For asynchronous usage:

from openperplex import OpenperplexAsync

api_key = "your_api_key"
client_async = OpenperplexAsync(api_key)

4. Make Your First API Calls

Openperplex provides a simple and powerfull interface for performing web searches.

4.1 search / search_stream

Synchronous:

result = client_sync.search(
    query="What are the latest developments in AI?",
    model="o3-mini-high",
    date_context="2024-08-25",
    location="us",
    response_language="en",
    answer_type="text",
    search_type="general",
    return_citations=False,
    return_sources=False,
    return_images=False,
    recency_filter="anytime"
)

print(result)

# Streaming search
for chunk in client_sync.search_stream(
    query="Explain quantum computing",
    model="o3-mini-high",
    date_context="2024-08-25",
    location="us",    
    response_language="en",
    answer_type="text",
    search_type="general",
    return_citations=False,
    return_sources=False,
    return_images=False,
    recency_filter="anytime"
):
    print(result)

Asynchronous:

import asyncio

async def search_async():
    # Non-streaming search
    result = await client_async.search(
        query="What are the latest developments in AI?",
        model='o3-mini-high',
        date_context="2024-08-25",
        location="us",
        response_language="en",
        answer_type="text",
        search_type="general",
        return_citations=False,
        return_sources=False,
        return_images=False,
        recency_filter="anytime"
    )
    print(result)

    # Streaming search
    async for chunk in client_async.search_stream(
        query="Explain quantum computing",
        model='o3-mini-high',
        date_context="2024-08-25",
        location="us",
        response_language="en",
        answer_type="text",
        search_type="general",
        return_citations=False,
        return_sources=False,
        return_images=False,
        recency_filter="anytime"
    ):
        print(chunk)

asyncio.run(search_async())

4.2. custom_search / custom_search_stream

The custom search endpoints allow you to tailor both your system prompts and user prompts to fit your specific needs.

Synchronous:

# Non-streaming custom search
result = client_sync.custom_search(
    system_prompt="You are a helpful assistant.",
    user_prompt="Explain the theory of relativity",
    model='o3-mini-high',
    location="us",
    search_type="general",
    return_images=False,
    return_sources=False,
    temperature=0.2,
    top_p=0.9,
    recency_filter="anytime"
)
print(result)

# Streaming custom search
for chunk in client_sync.custom_search_stream(
    system_prompt="You are a helpful assistant.",
    user_prompt="Explain the theory of relativity",
    model='o3-mini-high',
    location="us",
    search_type="general",
    return_images=False,
    return_sources=False,
    temperature=0.2,
    top_p=0.9,
    recency_filter="anytime"
):
    print(chunk)

4.3 Scrap TEXT from URL

#sync
result = client_sync.get_website_text("https://www.example.com")
print("TEXT : ",result.get("text"))


#async
result = await client_async.get_website_text("https://www.example.com")
print("TEXT : ",result.get("text"))

4.4 Retrieve text in markdown format from an URL

#sync
result = client_sync.get_website_markdown("https://www.example.com")
print(result.markdown)

#async
result = await client_async.get_website_markdown("https://www.example.com")
print(result.markdown)

4.5 Get a screenshot of an URL

#sync
result = client_sync.get_website_screenshot("https://www.example.com")
print(f"Screenshot available at: {result['url']}")

#async
result = await client_async.get_website_screenshot("https://www.example.com")
print(f"Screenshot available at: {result['url']}")

4.5 URL-based Querying

#sync
response = client_sync.query_from_url(
    url="https://www.example.com/article",
    query="What is the main topic of this article?",
    model='o3-mini-high',
    response_language="it",
    answer_type="text", # default is "text" if not specified

)
print(response)

#async
response = await client_async.query_from_url(
    url="https://www.example.com/article",
    query="What is the main topic of this article?",
    model='o3-mini-high',
    response_language="it",
    answer_type="text" # default is "text" if not specified
)
print(response)