Perplexity ↗

Original Documentation

This guide demonstrates how to use Perplexity AI with Instructor to generate structured outputs. You’ll learn how to use Perplexity’s Sonar models with Pydantic to create type-safe, validated responses.

Prerequisites#

You’ll need to sign up for a Perplexity account and get an API key. You can do that here.

export PERPLEXITY_API_KEY=<your-api-key-here>
pip install "instructor[perplexity]"

Perplexity AI#

Perplexity AI provides access to powerful language models through their API. Instructor supports structured outputs with Perplexity’s models using the OpenAI-compatible API.

Sync Example#

import instructor
from pydantic import BaseModel

client = instructor.from_provider(
    "perplexity/sonar-small-online",
    api_key=os.getenv("PERPLEXITY_API_KEY"),
    base_url="https://api.perplexity.ai",
)


class User(BaseModel):
    name: str
    age: int


# Create structured output
user = client.create(
    messages=[
        {"role": "user", "content": "Extract: Jason is 25 years old"},
    ],
    response_model=User,
)

print(user)
# > User(name='Jason', age=25)

Async Example#

import instructor
from pydantic import BaseModel
import asyncio

async_client = instructor.from_provider(
    "perplexity/sonar-small-online",
    async_client=True,
)


class User(BaseModel):
    name: str
    age: int


async def extract_user():
    user = await client.create(
        messages=[
            {"role": "user", "content": "Extract: Jason is 25 years old"},
        ],
        response_model=User,
    )
    return user


# Run async function
user = asyncio.run(extract_user())
print(user)
# > User(name='Jason', age=25)

Nested Objects#

import os
from openai import OpenAI
import instructor
from pydantic import BaseModel

# Initialize with API key
client = instructor.from_provider(
    "perplexity/sonar-small-online",
    api_key=os.getenv("PERPLEXITY_API_KEY"),
    base_url="https://api.perplexity.ai",
)


class Address(BaseModel):
    street: str
    city: str
    country: str


class User(BaseModel):
    name: str
    age: int
    addresses: list[Address]


# Create structured output with nested objects
user = client.create(
    messages=[
        {
            "role": "user",
            "content": """
            Extract: Jason is 25 years old.
            He lives at 123 Main St, New York, USA
            and has a summer house at 456 Beach Rd, Miami, USA
        """,
        },
    ],
    response_model=User,
)

print(user)
#> User(
#>     name='Jason',
#>     age=25,
#>     addresses=[
#>         Address(street='123 Main St', city='New York', country='USA'),
#>         Address(street='456 Beach Rd', city='Miami', country='USA')
#>     ]
#> )

Supported Modes#

Perplexity AI currently supports the following mode with Instructor:

PERPLEXITY_JSON: Direct JSON response generation

import os
from openai import OpenAI
import instructor
from instructor import Mode
from pydantic import BaseModel

# Initialize client with base URL
client = instructor.from_provider(
    "perplexity/sonar-small-online",
    api_key=os.getenv("PERPLEXITY_API_KEY"),
    base_url="https://api.perplexity.ai",
)


class User(BaseModel):
    name: str
    age: int


# Create structured output
user = client.create(
    messages=[
        {"role": "user", "content": "Extract: Jason is 25 years old"},
    ],
    response_model=User,
)

print(user)
# > User(name='Jason', age=25)

Additional Resources#

Link last verified June 17, 2026. View original ↗

Source: Instructor Docs

Link last verified: 2026-03-04