Руководство по API Perplexity: пошаговое создание ответа с заземлением по истоку

API PERPLEXITY · УЧЕБНОЕ ПОСОБИЕ ПО PYTHON · 2026

В этом руководстве по API Perplexity рассказывается, как создать скрипт на Python, который возвращает ответ с гиперссылками на веб-источники. Используйте API Agent для отправки вопроса, чтения ответа, сопоставления маркеров цитирования с идентификаторами источников и экспорта файла в формате Markdown для просмотра.

На протяжении всего текста мы будем использовать один вопрос: Как в небольшом проекте на Python следует использовать виртуальные среды и управлять зависимостями? Начните с простого запроса, а затем добавьте обработку исходных данных и доменные фильтры. Вам потребуются базовые знания языка Python и учетная запись разработчика Perplexity с настроенной системой оплаты API.

Если вы тоже используете ИИ в повседневной исследовательской работе и при написании текстов, Perplexity на GlobalGPT предоставляет доступ в рамках универсальной рабочей среды на базе искусственного интеллекта, что позволяет сократить необходимость переключения между отдельными инструментами. Данный рабочий процесс для конечных пользователей не связан с ключом разработчика и системой биллинга API, используемыми в данном случае.

Быстрый ответ: Используйте быстро Предварительная настройка агента для первого ответа на основе веб-данных, прочитать response.output_text за ответ и прочитайте результаты_поиска элемент в response.output для источников. Сопоставьте каждый встроенный маркер с источником по возвращаемому id. Ссылка означает, что “в ответе указано на этот результат”; она не гарантирует, что на данной странице доказаны все утверждения.

Пример статуса: Синтаксис запроса соответствует официальной документации, проверенной 28 сентября 2026 года. Работа инструмента для создания ссылок была проверена с использованием автономных примеров данных; для целей данного руководства платные запросы к API не выполнялись. Записи источников, показанные на иллюстрации, являются примерами для пояснения.

• Какой API Perplexity следует использовать?
• Шаг 1: Получите ключ API и настройте Python
• Шаг 2: Отправьте свой первый запрос с заземлением источника
• Шаг 3: Извлеките ответ и сопоставьте его с источниками
• Шаг 4: Уточните ответ с помощью фильтров поиска
• Шаг 5: Сохраните полный ответ с гиперссылками на источники
• Потоковая и структурированная вывод данных
• Расходы и типичные ошибки
• Переход от старого руководства по Sonar
• Часто задаваемые вопросы

Руководство по API Perplexity: как выбрать подходящий API

Это интерфейсы для разработчиков. В чат-приложении аналогичные функции могут быть реализованы иначе; в нашем обзоре Особенности Perplexity описывает взаимодействие с пользователем.

Perplexity’s Краткое руководство по официальному API группирует свои продукты для разработчиков в зависимости от задачи, которую необходимо выполнить. Выберите минимальную область, данные с которой действительно нужны вашему приложению.

В этом руководстве выбран вариант «Агент», поскольку вам нужен готовый ответ с указанием источников. Что касается более общего рабочего процесса исследования, ознакомьтесь с нашим руководством по использование Perplexity в научных исследованиях.

О Sonar: Текущий обзор миграции отмечается, что функция автодополнения в чате Sonar по-прежнему поддерживается, и для всех новых проектов рекомендуется использовать Agent. Поэтому в данном руководстве используется именно Agent. Не следует делать вывод о том, что старая интеграция перестала работать, исходя из срока, указанного в более старом руководстве.

Шаг 1: Получите ключ API и настройте Python

Создать ключ и подготовить счета

Откройте консоль API Perplexity, выберите или создайте проект, который будете использовать, настройте оплату по API и создайте ключ. Храните его на сервере. Оплата за API для разработчиков осуществляется отдельно от подписок для пользователей; перед отправкой запросов проверьте баланс вашего проекта.

Установите официальный SDK

python -m venv .venv

# macOS/Linux: выберите эту команду активации
source .venv/bin/activate

# Windows PowerShell: вместо этого используйте эту команду
.venv\Scripts\Activate.ps1

python -m pip install --upgrade perplexityai

Для выполнения приведенного ниже кода используйте Python версии 3.10 или более поздней. Активируйте среду с помощью команды, соответствующей вашей операционной системе, а затем установите SDK. Если PowerShell блокирует активацию, воспользуйтесь .venv\Scripts\python.exe вместо python для установки и запуска скрипта.

Название пакета — perplexityai, тогда как импорт в Python выглядит следующим образом: растерянность. Используйте виртуальную среду, чтобы зависимости этого руководства не повлияли на другой проект.

В данном примере используется вопрос, связанный с программированием, поскольку его утверждения можно проверить с помощью актуальной документации. Наше руководство по Perplexity для кодирования объясняет, какое место занимает поддержка со стороны исследователей на фоне самостоятельного тестирования кода.

Укажите ключ API в качестве переменной среды

# macOS/Linux
export PERPLEXITY_API_KEY="ваш-ключ"

# Windows PowerShell
$env:PERPLEXITY_API_KEY = "ваш-ключ"

В SDK говорится: PERPLEXITY_API_KEY при создании клиента. Не вставляйте ключ в блокнот, не добавляйте его в репозиторий Git и не отправляйте его в браузер. Если вы используете файл .env локально, не включайте этот файл в систему контроля версий и загружайте его с помощью выбранной вами библиотеки переменных среды.

Шаг 2: Отправьте свой первый запрос с заземлением источника

Краткое руководство по API Agent документы ПОСТ https://api.perplexity.ai/v1/agent. Его клиент на Python обертывает запрос с помощью client.responses.create(). . быстро В этой настройке по умолчанию включен веб-поиск, благодаря чему первый пример остается кратким.

from perplexity import Perplexity

client = Perplexity()

question = (
    "Как в небольшом проекте на Python следует использовать виртуальные среды"
    "и управлять зависимостями?"
)

response = client.responses.create(
    preset="fast",
    input=question,
)

print(response.output_text)

Сохраните фрагмент кода как first_request.py, а затем запустите python first_request.py в том же терминале, где вы задали ключ. При успешном вызове должен вывести непустой текст ответа. Если вам нужны доказательства результата, перейдите к этапу извлечения исходного кода; одного текста недостаточно для полной проверки.

Свойство «удобство» output_text выводит окончательный текст ответа. Сохраните также весь объект ответа: исходные записи и сведения об использовании содержатся в тексте вывода, а не только в напечатанном абзаце.

Тот же запрос с помощью cURL

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "fast",
    "input": "Как небольшому проекту на Python следует использовать виртуальные среды и управлять зависимостями?"
  }'

В этом примере cURL используется синтаксис Bash для macOS/Linux или оболочки, совместимой с Bash. Каждый запуск формирует новый платный запрос. Используйте его только в том случае, если вам нужно отделить проблему с конечной точкой от проблемы с Python; не запускайте каждую версию просто для того, чтобы повторить пример.

Эквивалент на стороне сервера на JavaScript

В Node.js 18+ включено загрузить, поэтому для серверного теста работоспособности не требуется никаких дополнительных библиотек. Прочитайте исходный код вывод элементы в ответе JSON; SDK для Python предоставляет удобный output_text аксессуар.

const res = await fetch("https://api.perplexity.ai/v1/agent", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PERPLEXITY_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    preset: "fast",
    input: "Как небольшому проекту на Python следует использовать виртуальные среды и управлять зависимостями?"
  })
});
if (!res.ok) throw new Error(`Perplexity HTTP ${res.status}`);
console.log(await res.json());

Шаг 3: Извлеките ответ и сопоставьте его с источниками

Официальные рекомендации по составлению цитат отделяет прозу от записей, содержащих доказательства. Источники поступают в виде вывод элемент типа результаты_поиска. Прочитайте эту статью результаты и сопоставить каждый маркер цитирования с результатом id. Результат имеет заголовок и URL-адрес; перед отображением необходимо обработать отсутствующие значения.

Эта последняя деталь имеет значение. Не следует полагать, что “ссылка 1” всегда является первым элементом массива после того, как другой инструмент добавляет в него элемент. Сначала создайте таблицу сопоставления по идентификаторам, а затем определите маркеры, которые действительно появляются в ответе.

def field(obj, name, default=None):
    return obj.get(name, default), если obj является словарем, иначе — getattr(obj, name, default)

def source_index(output):
    sources = {}
    for item in output or []:
 if field(item, "type") != "search_results":
 continue
 for result in field(item, "results", []) or []:
            sid, url = field(result, "id"), field(result, "url")
 if sid is None:
 continue
 key = str(sid)
 if key in sources and field(sources[key], "url") != url:
                raise ValueError(f"Конфликтующие URL-адреса для ID источника {key}")
 sources[key] = result
    return sources

sources = source_index(response.output)
print(sources.get("7"))  # ID источника, а не позиция 7 в массиве

Приведенный ниже полный скрипт распознает [1] и [web:1], задокументированные формы цитирования для распространённых предустановок. Приведённый выше помощник обрабатывает как объекты SDK, так и словари, а также отклоняет конфликтующие URL-адреса, назначенные одному и тому же идентификатору. Он не перенумеровывает результаты и не пытается угадать отсутствующий источник.

Более подробно о качестве цитирования см. в нашей Руководство по точности цитирования Perplexity. Ссылка — это контрольный след; вашему приложению по-прежнему необходима политика обращения с устаревшими страницами, дубликатами URL-адресов и неподтвержденными утверждениями.

Например, если в возвращаемом массиве идет ID 2, за которым следует ID 7, то маркер [7] должен соотноситься с ID 7. Если один и тот же URL указан под ID 7 и 9, можно отобразить этот URL один раз, сохранив при этом оба ID. Если ID 8 так и не поступит, сохраните [8] отобразить и пометить как несоответствующий.

Шаг 4: Уточните ответ с помощью фильтров поиска

Как только базовый запрос начнёт работать, сузьте круг поиска, если в вашем вопросе чётко определены границы компетенции. В случае с пакетами Python документация по языку и руководство по созданию пакетов являются лучшими отправными точками, чем произвольное руководство.

response = client.responses.create(
    preset="fast",
    input=(
 "Как в небольшом проекте на Python следует использовать виртуальные среды "
 "и управлять зависимостями? Приведите ссылки на руководства, которыми вы пользуетесь."
    ),
    tools=[
 {
 "type": "web_search",
 "filters": {
 "search_domain_filter": [
 "docs.python.org",
                    "packaging.python.org",
 ]
 },
 }
    ],
)

Этот фильтр должен быть указан в настройках инструмента веб-поиска. В документации по миграции также описано фильтр_по_свежести_поиска для вопросов, требующих оперативного ответа. Используйте критерий «актуальности», если вопрос зависит от недавних выпусков или новостей; слишком узкое сочетание тематики и даты может привести к недостаточному количеству данных.

Если у вас есть вопрос о релизах за последний месяц, добавьте "search_recency_filter": "месяц" рядом с фильтр_по_домену_поиска. Не включайте его в пример с виртуальной средой: в стабильной версии документации дата публикации может быть более ранней. Если вы переходите с предустановленной модели на выбранную напрямую, обязательно включите инструмент веб-поиска.

В процессе разработки сравнивайте отфильтрованные и неотфильтрованные результаты. Если ответ меняется, запишите причину: фильтр может удалить полезный контекст или же страницы с низким авторитетом, которые сбивали модель с толку. Это решение, основанное на оценке качества, а не гарантия того, что каждая оставшаяся страница является правильной.

Если вашему приложению требуются только ссылки с ранжированием и фрагменты, вызовите функцию API поиска и самостоятельно выполнить синтез. Такое разделение может упростить проверку и кэширование. Для более подробного сравнения с Google см. Чем Perplexity отличается от Google.

Шаг 5: Сохраните полный ответ с гиперссылками на источники

Сохраните следующее как perplexity_tutorial.py. Он является автономным: включает в себя вспомогательную программу для работы с исходным кодом, применяет доменный фильтр документации Python, преобразует найденные маркеры цитирования в ссылки, группирует дубликаты URL-адресов без потери идентификаторов и сохраняет полный ответ SDK вместе с кодом Markdown.

from pathlib import Path
from collections import defaultdict
from urllib.parse import urlsplit
import json
import re

QUESTION = (
    "How should a small Python project use virtual environments "
    "and manage dependencies?"
)
# Supports the documented [1] and [web:1] forms in prose answers.
CITATION_RE = re.compile(r"(?<!!)\[(?:web:)?(\d+)\](?!\()")

def field(obj, name, default=None):
    return obj.get(name, default) if isinstance(obj, dict) else getattr(obj, name, default)

def source_index(output):
    sources = {}
    for item in output or []:
        if field(item, "type") != "search_results":
            continue
        for result in field(item, "results", []) or []:
            sid, url = field(result, "id"), field(result, "url")
            if sid is None:
                continue
            key = str(sid)
            if key in sources and field(sources[key], "url") != url:
                raise ValueError(f"Conflicting URLs for source ID {key}")
            sources[key] = result
    return sources

def safe_url(value):
    if not isinstance(value, str):
        return None
    parsed = urlsplit(value)
    if parsed.scheme not in ("http", "https") or not parsed.netloc:
        return None
    # Protect a Markdown angle-bracket destination.
    return value.replace("<", "%3C").replace(">", "%3E").replace(" ", "%20")

def md_label(value):
    return re.sub(r"([\\\[\]<>])", r"\\\1", str(value).replace("\n", " "))

def export_markdown(answer, output, question=QUESTION):
    sources = source_index(output)
    cited = list(dict.fromkeys(CITATION_RE.findall(answer)))
    missing = [
        sid for sid in cited
        if sid not in sources or not safe_url(field(sources[sid], "url"))
    ]
    def link(match):
        sid = match.group(1)
        url = safe_url(field(sources.get(sid, {}), "url"))
        return f"[{match.group(0)[1:-1]}](<{url}>)" if url else match.group(0)

    # Keep every ID when the same URL appears under different IDs.
    grouped = defaultdict(list)
    titles = {}
    for sid in cited:
        source = sources.get(sid, {})
        url = safe_url(field(source, "url"))
        if url:
            grouped[url].append(sid)
            titles.setdefault(url, field(source, "title") or url)

    lines = ["# Source-grounded answer", "", question, "",
             CITATION_RE.sub(link, answer), "", "## Cited sources", ""]
    for url, ids in grouped.items():
        lines.append(f"- IDs {', '.join(ids)}: [{md_label(titles[url])}](<{url}>)")
    if missing:
        lines.append("- Unmatched or unusable source IDs: " + ", ".join(missing))
    if not cited:
        lines.append("- No recognized inline citations; evidence not verified.")
    lines.extend(["", "Source links require review; matching IDs does not verify claims."])
    return "\n".join(lines) + "\n"

def main():
    from perplexity import Perplexity
    response = Perplexity().responses.create(
        preset="fast",
        input=QUESTION,
        tools=[{"type": "web_search", "filters": {
            "search_domain_filter": ["docs.python.org", "packaging.python.org"]
        }}],
    )
    answer = response.output_text or ""
    if not answer.strip():
        raise RuntimeError("No answer text returned; inspect response status and errors.")
    Path("perplexity-response.json").write_text(
        response.model_dump_json(indent=2), encoding="utf-8"
    )
    Path("perplexity-answer.md").write_text(
        export_markdown(answer, response.output), encoding="utf-8"
    )
    print("Saved perplexity-answer.md and perplexity-response.json")

if __name__ == "__main__":
    main()

Запустить python perplexity_tutorial.py из каталога вашего проекта. Он записывает perplexity-answer.md и perplexity-response.json там, заменяя файлы с такими именами более ранними версиями. Файл в формате Markdown содержит вопрос, ссылку на ответ, цитируемые источники и все несоответствующие идентификаторы. Файл в формате JSON хранит возвращаемый результат и информацию об использовании для диагностики.

Парсер предназначен для обработки описанных в документации форм с одним маркером в прозе. Это не полноценный парсер Markdown: если ваше приложение требует обработки произвольного Markdown, примеров кода или цитат, таких как [1,2], добавьте рендерер с поддержкой синтаксиса и тесты для этого формата. Не переинтерпретируйте неизвестные маркеры без предупреждения.

Проверьте, содержится ли ответ на указанной странице

В данном примере проверьте, действительно ли в указанной документации объясняются вопросы изоляции среды и установки зависимостей. Ссылка на главную страницу Python менее полезна, чем соответствующий раздел документации. Если в ответе рекомендуется конкретная команда, перед её запуском проверьте, для какой операционной системы и какой версии Python она предназначена. Марк утверждает, что приведённый текст не подтверждает статус «нерешённого».

При необходимости добавьте потоковый или структурированный вывод

Потоковое вещание

Потоковая передача данных позволяет снизить ощущаемую задержку в интерфейсе чата. В руководстве по миграции агентов описаны события «дельта» текста, такие как response.output_text.delta. Отображайте эти дельты по мере их поступления, но при этом собирайте и элементы окончательного ответа, чтобы ваш пользовательский интерфейс мог отобразить источники после завершения ответа. Сам по себе поток текста не является списком источников.

Ниже приводится только текстовое отображение. Сохраните экспорт в непотоковом режиме для первой полной исходной записи; в производственной реализации потокового режима также необходимо собирать события, связанные с инструментами и выводом данных, а также обрабатывать прерванные или завершившиеся сбоем циклы выполнения.

stream = client.responses.create(
    preset="fast", input=question, stream=True
)
for event in stream:
    if event.type == "response.output_text.delta":
 print(event.delta, end="", flush=True)

Структурированный вывод

Используйте структурированный ответ, если в последующем коде требуются такие поля, как ответ, примечание_об_уверенности и дополнительные вопросы. Сохраняйте идентификаторы источников в отдельном поле или оставляйте исходные данные, выведенные Agent, чтобы схема не скрывала эти данные. Проверьте схему на собственных тестовых примерах, прежде чем использовать её в рабочем процессе.

В справочнике по миграции сохраняется формат_ответа с тип: "json_schema" для структурированного вывода. Определите обязательные поля и, при необходимости, запретите использование неожиданных свойств. Проверки корректности схемы касаются формы, а не содержания: идентификаторы источника по-прежнему должны соотноситься с фактически возвращаемыми записями, а метка достоверности, заданная моделью, не является показателем точности.

Стоимость API Perplexity и типичные ошибки

Официальная страница с ценами на Perplexity, по состоянию на 28 сентября 2026 г., разделяет токены модели «Агент» и вызовы инструментов. Ниже приведены тарифы на использование инструментов и поиск в долларах США. быстро Предварительная настройка агента и search_type: "fast" существуют различные варианты настроек; не следует делать выводы о скорости поиска на основании названия предустановки.

Пример: Стоимость 1 000 стандартных запросов веб-поиска плюс 1 000 запросов на получение URL-адресов $3.00 — расходы на инструмент ($2.50 + $0.50) — до учета токенов модели или других сборов. Это расчетная нагрузка, а не фактическая стоимость для целей данного учебного пособия. Один запрос агента может задействовать несколько инструментов. При наличии возможности проверьте использование.стоимость.общая_стоимость по завершенному ответу.

API поиска выставляет счета за успешные запросы, включая те, которые не возвращают результатов; стоимость запроса не включает дополнительную плату за токены. Расходы на работу агента зависят от токенов модели и инструментов. При сравнении рабочего процесса с обработкой ответов и рабочего процесса, предусматривающего только поиск, следует учитывать эти единицы начисления отдельно.

Для сравнения бюджетов API наш Руководство по стоимости API Perplexity добавляет дополнительную информацию, однако официальная страница с ценами по-прежнему является основным источником актуальных тарифов.

Переход от старого руководства по Sonar

Во многих результатах поиска по-прежнему отображается старая форма «Завершение чата». В руководстве по миграции агентов используется прямое концептуальное сопоставление. Если вы сравниваете метки потребительской модели с предустановками API, ознакомьтесь с нашей инструкцией на что использует LLM Perplexity даёт общее представление, но не заменяет документацию по API Agent.

Читайте прямую трансляцию обзор миграции и сведения о миграции прежде чем вносить изменения в производственный код. Предустановленные сопоставления служат отправной точкой, но не гарантируют, что старые и новые модели обеспечат одинаковое качество, задержку или стоимость.

Часто задаваемые вопросы

API Perplexity является бесплатным?

Оплата за использование API производится по факту в соответствии с действующей документацией по быстрому запуску и ценам. Не следует полагать, что подписка для конечных пользователей, пробная версия или промо-кредит делают каждый запрос к API бесплатным.

Нужна ли мне версия Perplexity Pro для использования API?

Доступ к API и тарифный план «Pro» для конечных пользователей — это отдельные продукты. Создайте учетные данные для доступа к API и проверьте настройки оплаты за использование API для учетной записи разработчика, которую вы планируете использовать.

Что лучше использовать: Agent API или Search API?

Выбирайте «Агент», если вам нужен готовый, обоснованный ответ с указанием источников. Выбирайте «Поиск», если ваше приложение должно самостоятельно осуществлять ранжирование, фильтрацию и обобщение. Вы можете совместить «Поиск» с собственной моделью, если вам требуется строгий контроль над каждым этапом генерации.

Можно ли вызвать функцию Perplexity из JavaScript?

Да. Воспользуйтесь приведённым выше примером на Node.js со стороны сервера или официальным SDK для JavaScript. Храните ключ на сервере. При чтении необработанных данных JSON проанализируйте элементы вывода с указанием типов и примените те же правила сопоставления source-ID.

Гарантируется ли правильность ссылок Perplexity?

Нет. Ссылка указывает, на какой из найденных результатов указывает данный ответ. Вашему приложению или рецензенту по-прежнему необходимо проверить актуальность, достоверность источника и то, подтверждает ли данная страница именно это утверждение.

Почему мой парсер не нашёл никаких источников?

Просмотрите типы элементов необработанных результатов, убедитесь, что веб-поиск был выполнен, и проверьте, соответствует ли ваше регулярное выражение формату цитирования, заданному в настройках. Если маркер не отображается, сохраните ответ как «непроверенный» и проанализируйте запрос, а не добавляйте ссылку, основанную на догадках.

Может ли ключ API GlobalGPT заменить ключ API Perplexity?

GlobalGPT — это универсальная рабочая среда для повседневного использования искусственного интеллекта. Подписка и доступ к моделям в ней не связаны с учетной записью разработчика Perplexity, ключом API и кредитами API; в данном руководстве по Python используется именно учетная запись разработчика.

Практический контрольный список для запуска

• Создайте ключ на стороне сервера и подтвердите настройки оплаты API.
• Запустите минимальную версию быстро запросите разрешение перед добавлением фильтров или началом потоковой передачи.
• Сохраняйте полный ответ, а не только видимый текст ответа.
• Сопоставить маркеры цитирования с полученными идентификаторами источников и пометить несопоставленные маркеры.
• Проверьте указанные страницы на предмет обоснованности утверждений, актуальности и наличия дубликатов URL-адресов.
• Перед развертыванием еще раз ознакомьтесь с документацией по работе с Live Agent, ценам и миграции.

Теперь у вас есть основной шаблон для надёжной интеграции API Perplexity: задайте конкретный вопрос, дайте API-интерфейсу агента выполнить поиск, храните ответ и подтверждающие данные вместе и обеспечьте возможность проверки каждой ссылки. На этой основе добавьте кэширование, повторные попытки и свои собственные правила проверки в рамках того же рабочего процесса с использованием идентификатора источника.