# Perplexity API Documentation ## Authentication - Bearer token authentication required - Header: `Authorization: Bearer <token>` - Base URL: `https://api.perplexity.ai` ## Models | Model | Parameters | Context Length | Request Limit | |-------|------------|----------------|---------------| | `llama-3.1-sonar-small-128k-online` | 8B | 127,072 | 50/min | | `llama-3.1-sonar-large-128k-online` | 70B | 127,072 | 50/min | | `llama-3.1-sonar-huge-128k-online` | 405B | 127,072 | 50/min | *Note: System prompts don't affect search component. Use them for style/tone instructions.* ## Chat Completions Endpoint ### Request Details - **Method**: POST - **Endpoint**: `/chat/completions` - **Content-Type**: application/json ### Parameters #### Required Parameters - `model`: Model name (e.g., "llama-3.1-sonar-small-128k-online") - `messages`: Array of message objects: ```json { "role": "system" | "user" | "assistant", "content": "message text" } ``` #### Optional Parameters | Parameter | Description | Range/Values | |-----------|-------------|--------------| | `max_tokens` | Maximum response tokens | Model dependent | | `temperature` | Randomness | 0-2 (default: 0.2) | | `top_p` | Nucleus sampling | 0-1 (default: 0.9) | | `top_k` | Token filtering | 0-2048 (default: 0) | | `stream` | Enable streaming | boolean (default: false) | | `presence_penalty` | Topic diversity | -2 to 2 | | `frequency_penalty` | Repetition penalty | >0 | | `search_domain_filter` | Domain whitelist/blacklist | Array (beta) | | `return_images` | Include images | boolean (beta) | | `return_related_questions` | Get related questions | boolean (beta) | | `search_recency_filter` | Time filter | "month", "week", "day", "hour" | ### Response Format ```json { "id": "uuid", "model": "model-name", "object": "chat.completion", "created": timestamp, "citations": ["url1", "url2"], "choices": [{ "index": 0, "finish_reason": "stop", "message": { "role": "assistant", "content": "response" } }], "usage": { "prompt_tokens": 123, "completion_tokens": 456, "total_tokens": 579 } } ``` ## Code Examples ### cURL ```bash curl --request POST \ --url https://api.perplexity.ai/chat/completions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "model": "llama-3.1-sonar-small-128k-online", "messages": [ { "role": "system", "content": "Be precise and concise." }, { "role": "user", "content": "How many stars are there in our galaxy?" } ], "temperature": 0.2, "top_p": 0.9 }' ``` ### Python ```python import requests url = "https://api.perplexity.ai/chat/completions" headers = { "Authorization": "Bearer <token>", "Content-Type": "application/json" } payload = { "model": "llama-3.1-sonar-small-128k-online", "messages": [ { "role": "system", "content": "Be precise and concise." }, { "role": "user", "content": "How many stars are there in our galaxy?" } ], "temperature": 0.2, "top_p": 0.9 } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ### JavaScript ```javascript const options = { method: 'POST', headers: { 'Authorization': 'Bearer <token>', 'Content-Type': 'application/json' }, body: JSON.stringify({ "model": "llama-3.1-sonar-small-128k-online", "messages": [ { "role": "system", "content": "Be precise and concise." }, { "role": "user", "content": "How many stars are there in our galaxy?" } ], "temperature": 0.2, "top_p": 0.9 }) }; fetch('https://api.perplexity.ai/chat/completions', options) .then(response => response.json()) .then(console.log) .catch(console.error); ``` ## Beta Features & Rate Limits - Request elevated rate limits via [access form](https://perplexity.typeform.com/apiaccessform) - Beta features requiring approval: - Image support (`return_images`) - Related questions (`return_related_questions`) - Domain filtering (`search_domain_filter`) - limit 3 domains