​

Overview

• OpenAI-compatible base - Uses OpenAI’s chat format as foundation
• Web search parameters - Search mode, domain filters, recency filters, and location-based search
• Reasoning effort mapping - reasoning.effort mapped to Perplexity’s reasoning_effort with special handling for “minimal”
• Search results inclusion - Citations, search results, and videos included in response
• Special usage tracking - Citation tokens, search queries, and reasoning tokens tracked separately

​

Supported Operations

​

1. Chat Completions

​

Request Parameters

​

Perplexity-Specific Constraints

• No function calling: tools and tool_choice are silently dropped
• Dropped parameters: stop, logit_bias, logprobs, top_logprobs, seed, parallel_tool_calls, service_tier
• Reasoning: Uses reasoning_effort instead of reasoning object (see Reasoning & Effort)

​

Perplexity-Specific Parameters

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar",
    "messages": [{"role": "user", "content": "What is the latest news?"}],
    "search_mode": "web",
    "language_preference": "en",
    "return_images": true,
    "return_related_questions": true,
    "disable_search": false,
    "search_domain_filter": ["news.example.com"],
    "search_recency_filter": "week"
  }'

resp, err := client.ChatCompletionRequest(ctx, &schemas.BifrostChatRequest{
    Provider: schemas.Perplexity,
    Model:    "sonar",
    Input:    messages,
    Params: &schemas.ChatParameters{
        ExtraParams: map[string]interface{}{
            "search_mode": "web",
            "language_preference": "en",
            "return_images": true,
            "return_related_questions": true,
            "disable_search": false,
            "search_domain_filter": []string{"news.example.com"},
            "search_recency_filter": "week",
        },
    },
})

​

Search Parameters

​

Media Parameters

​

Web Search Options

{
  "web_search_options": [
    {
      "search_context_size": "high",
      "user_location": {
        "latitude": 40.7128,
        "longitude": -74.0060,
        "city": "New York",
        "country": "US",
        "region": "NY"
      },
      "image_search_relevance_enhanced": true
    }
  ]
}

​

Reasoning & Effort

​

Parameter Mapping

• reasoning.effort → reasoning_effort
• Supported efforts: "low", "medium", "high"
• Special conversion: "minimal" → "low" (Perplexity normalizes to low/medium/high)
• reasoning.max_tokens is silently dropped (Perplexity doesn’t support token budget control)

​

Example

// Request
{"reasoning": {"effort": "high"}}

// Perplexity conversion
{"reasoning_effort": "high"}

// Special case: "minimal" effort
{"reasoning": {"effort": "minimal"}}
→ {"reasoning_effort": "low"}

​

Response Conversion

​

Search Results Inclusion

• citations[] - Source citations from search
• search_results[] - Full search results with metadata
• videos[] - Video results from search

​

Usage Details

​

Example Response

{
  "id": "...",
  "choices": [...],
  "usage": {
    "prompt_tokens": 100,
    "completion_tokens": 150,
    "total_tokens": 250,
    "completion_tokens_details": {
      "citation_tokens": 25,
      "num_search_queries": 3,
      "reasoning_tokens": 40
    },
    "cost": { "prompt_cost": 0.001, "completion_cost": 0.002 }
  },
  "citations": ["https://example.com/article1", "https://example.com/article2"],
  "search_results": [
    {
      "title": "...",
      "url": "...",
      "snippet": "...",
      "date": "2025-01-15"
    }
  ],
  "videos": [
    {
      "title": "...",
      "url": "...",
      "duration": 300
    }
  ]
}

​

Streaming

• chat.completion.chunk events with delta updates
• Standard OpenAI finish reason mapping

​

Caveats

​

2. Responses API

​

Request Parameters

​

Parameter Mapping

​

Extra Parameters

curl -X POST http://localhost:8080/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar",
    "instructions": "You are a helpful assistant with web search capabilities",
    "input": "What is the latest news in technology?",
    "search_mode": "news",
    "return_images": true
  }'

resp, err := client.ResponsesRequest(ctx, &schemas.BifrostResponsesRequest{
    Provider: schemas.Perplexity,
    Model:    "sonar",
    Input:    messages,
    Params: &schemas.ResponsesParameters{
        Instructions: schemas.Ptr("You are a helpful assistant with web search capabilities"),
        ExtraParams: map[string]interface{}{
            "search_mode": "news",
            "return_images": true,
        },
    },
})

​

Conversion Details

• instructions becomes a system message prepended to input messages
• input (string or array) converted to user message(s)
• Response converted to Responses API format with same search results and extended usage details

​

Response Format

​

Streaming