Image Filters Guide

Control image results with domain and format filters using the Perplexity API.

The image_domain_filter and image_format_filter parameters allow you to control the sources and file types of image results returned by the Sonar models.

You can include a maximum of 10 entries in each of the filter lists. These filters currently apply only when "return_images": true is set in your request.

Overview

The image_domain_filter and image_format_filter parameters give you fine-grained control over image results returned by the Sonar models. Use these filters to:

• Exclude specific image providers (e.g., Getty Images)
• Restrict to a specific file format (e.g., .gif)

To use these filters, your request must include "return_images": true.

{
  "image_domain_filter": ["-gettyimages.com"],
  "image_format_filter": ["gif"]
}

• Prefix domains with - to exclude them • Use lowercase file extensions like gif, jpg, or png ⸻

Examples

1. Exclude Specific Image Domains

This request filters out images from Getty Images.

cURL

curl --request POST \
  --url https://api.perplexity.ai/chat/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "sonar",
    "return_images": true,
    "image_domain_filter": ["-gettyimages.com"],
    "messages": [
      {"role": "user", "content": "What is the weather like today in London?"}
    ]
  }'

⸻

2. Only Return GIFs

This request restricts results to GIF images.

cURL

curl --request POST \
  --url https://api.perplexity.ai/chat/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "sonar",
    "return_images": true,
    "image_format_filter": ["gif"],
    "messages": [
      {"role": "user", "content": "Show me a funny cat gif"}
    ]
  }'

⸻

3. Combine Domain and Format Filters

You can combine both filters for precise control.

cURL

curl --request POST \
  --url https://api.perplexity.ai/chat/completions \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "sonar",
    "return_images": true,
    "image_domain_filter": ["-gettyimages.com"],
    "image_format_filter": ["gif"],
    "messages": [
      {"role": "user", "content": "Show me a gif of a dog"}
    ]
  }'

⸻

Best Practices

Domain Filtering • Use simple domain names like example.com or -gettyimages.com • Do not include http://, https://, or subdomains

Format Filtering • File extensions must be lowercase: [“jpg”], not [“JPG”] • Omit dot prefix: use gif, not .gif

Filter Strategy • You can mix inclusion and exclusion in domain filters • Keep lists short (≤10 entries) for performance and relevance

Performance Notes • Filters may slightly increase response time • Overly restrictive filters may reduce result quality or quantity