Image Attachments

Overview

Both the Agentic Research API and Chat Completions API support image analysis through direct image uploads. Images can be provided either as base64 encoded strings within a data URI or as standard HTTPS URLs.

When using base64 encoding, the API currently only supports images up to 50 MB per image.
Supported formats for base64 encoded images: PNG (image/png), JPEG (image/jpeg), WEBP (image/webp), and GIF (image/gif).
When using an HTTPS URL, the model will attempt to fetch the image from the provided URL. Ensure the URL is publicly accessible.

Examples

Agentic Research API
Chat Completions API

Base64 Encoded Data
HTTPS URL

Use this method when you have the image file locally and want to embed it directly into the request payload. Remember the 50MB size limit and supported formats (PNG, JPEG, WEBP, GIF).

import base64
from perplexity import Perplexity

client = Perplexity(api_key="pplx-KEY")

# Read and encode image as base64
def encode_image(image_path):
    with open(image_path, "rb") as image_file:
        return base64.b64encode(image_file.read()).decode("utf-8")

image_path = "image.png"
base64_image = encode_image(image_path)

# Analyze the image
response = client.responses.create(
    model="openai/gpt-5-mini",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "what's in this image?"},
                {
                    "type": "input_image",
                    "image_url": f"data:image/png;base64,{base64_image}",
                },
            ],
        }
    ],
)

print(response.output_text)

Use this method when you have a publicly accessible image URL. The model will fetch the image from the provided URL.

from perplexity import Perplexity

client = Perplexity(api_key="pplx-KEY")

image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"

# Analyze the image
response = client.responses.create(
    model="openai/gpt-5-mini",
    input=[
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "Can you describe the image at this URL?"},
                {
                    "type": "input_image",
                    "image_url": image_url,
                },
            ],
        }
    ],
)

print(response.output_text)

Base64 Encoded Data
HTTPS URL

Use this method when you have the image file locally and want to embed it directly into the request payload. Remember the 50MB size limit and supported formats (PNG, JPEG, WEBP, GIF).

from perplexity import Perplexity
import base64

client = Perplexity()

# Read and encode image as base64
try:
    with open("path/to/your/image.png", "rb") as image_file:
        base64_image = base64.b64encode(image_file.read()).decode("utf-8")
    image_data_uri = f"data:image/png;base64,{base64_image}"
except FileNotFoundError:
    print("Error: Image file not found.")
    exit()

# Analyze the image
try:
    completion = client.chat.completions.create(
        model="sonar-pro",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Can you describe this image?"},
                    {"type": "image_url", "image_url": {"url": image_data_uri}}
                ]
            }
        ]
    )
    print(completion.choices[0].message.content)
except Exception as e:
    print(f"API Request failed: {e}")

Use this method to reference an image hosted online. Ensure the URL is publicly accessible and points directly to the image file.

from perplexity import Perplexity

client = Perplexity()

image_https_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"

# Analyze the image
try:
    completion = client.chat.completions.create(
        model="sonar-pro",
        messages=[
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": "Can you describe the image at this URL?"},
                    {"type": "image_url", "image_url": {"url": image_https_url}}
                ]
            }
        ]
    )
    print(completion.choices[0].message.content)
except Exception as e:
    print(f"API Request failed: {e}")

Request Format

Agentic Research API

Images must be embedded in the input array when using message array format. Each image should be provided using the following structure:

{
  "role": "user",
  "content": [
    {
      "type": "input_text",
      "text": "What's in this image?"
    },
    {
      "type": "input_image",
      "image_url": "<IMAGE_URL_OR_BASE64_DATA>"
    }
  ]
}

The image_url field accepts either:

A URL of the image: A publicly accessible HTTPS URL pointing directly to the image file
The base64 encoded image data: A data URI in the format data:image/{format};base64,{base64_content}

Chat Completions API

Images must be embedded in the messages array, alongside any text input. Each image should be provided using the following structure:

{
  "type": "image_url",
  "image_url": {
    "url": "<IMAGE_URL_OR_BASE64_DATA>"
  }
}

The url field accepts either:

A URL of the image: A publicly accessible HTTPS URL pointing directly to the image file
The base64 encoded image data: A data URI in the format data:image/{format};base64,{base64_content}

Pricing

Images are tokenized based on their pixel dimensions using the following formula:

tokens = (width px × height px) / 750

Examples:

A 1024×768 image would consume: (1024 × 768) / 750 = 1,048 tokens
A 512×512 image would consume: (512 × 512) / 750 = 349 tokens

These image tokens are then priced according to the input token pricing of the model you’re using. The image tokens are added to your total token count for the request alongside any text tokens.

Next Steps

Agentic Research API Quickstart

Get started with the Agentic Research API

Chat Completions API Quickstart

Get started with the Chat Completions API

Tools

Learn about web_search and fetch_url tools

Models

Explore available models for image analysis

Getting Started

Perplexity SDK

Search API

Grounded LLM

Admin & Management

Resources

Overview

Examples

Request Format

Agentic Research API

Chat Completions API

Pricing

Next Steps

Agentic Research API Quickstart

Chat Completions API Quickstart

Tools

Models

Getting Started

Perplexity SDK

Search API

Grounded LLM

Admin & Management

Resources

​Overview

​Examples

​Request Format

​Agentic Research API

​Chat Completions API

​Pricing

​Next Steps

Agentic Research API Quickstart

Chat Completions API Quickstart

Tools

Models

Overview

Examples

Request Format

Agentic Research API

Chat Completions API

Pricing

Next Steps