# Суммирование PDF с помощью Python — Учебник по API сводок PDF

Добавьте функцию суммаризации PDF в скрипт на Python, блокнот Jupyter или бэкенд всего за несколько строк. В этом руководстве рассматриваются аутентификация, первый запрос, формат ответа, стриминг, пакетная обработка папки и правильная обработка ошибок.

## Key facts

- Эндпоинт: POST https://pdf-summarize.com/api/summarize.php с использованием multipart/form-data, поле file.
- Авторизация: заголовок Authorization: Bearer sk_... — бесплатный ключ при регистрации, без кредитной карты.
- Параметры: length (short/medium/long/extensive), format (paragraph/bullets/mixed), outputLang (auto или код языка), includeKeywords.
- Ответ: JSON с полями summary, keywords, page_count, processing_time, requests_remaining.
- Добавьте ?stream=1, чтобы получать сводку в режиме реального времени через Server-Sent Events.

## Предварительные требования

- Python 3.8+ и библиотека `requests` (`pip install requests`).
- Ключ API: [создайте бесплатную учетную запись](/signup) и скопируйте ключ из панели управления. Рекомендуется хранить его в переменной окружения, а не в коде:

```bash
export PDF_SUMMARIZE_KEY="sk_live_..."
```

## Ваша первая сводка PDF на Python

1. **Установите requests** — pip install requests.
2. **Установите ключ API** — В переменной окружения PDF_SUMMARIZE_KEY.
3. **Отправьте PDF** — Как multipart/form-data с именем поля file.
4. **Прочитайте JSON** — Сама сводка находится в поле summary; также проверьте success и статус HTTP.

```python
import os
import requests

API_URL = "https://pdf-summarize.com/api/summarize.php"
API_KEY = os.environ["PDF_SUMMARIZE_KEY"]

def summarize_pdf(path, length="medium", fmt="bullets", lang="auto"):
    with open(path, "rb") as f:
        resp = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": (os.path.basename(path), f, "application/pdf")},
            data={"length": length, "format": fmt, "outputLang": lang, "includeKeywords": "1"},
            timeout=180,
        )
    data = resp.json()
    if resp.status_code != 200 or not data.get("success"):
        raise RuntimeError(f"{resp.status_code}: {data.get('error', data)}")
    return data

result = summarize_pdf("annual-report.pdf")
print(result["summary"])
print("Страниц:", result["page_count"], "| Ключевые слова:", result.get("keywords"))
```

## Ответ API

```json
{
  "success": true,
  "summary": "- Выручка выросла на 6% до...",
  "keywords": "выручка, маржа, прогноз, ...",
  "page_count": 48,
  "original_length": 182340,
  "summary_length": 1210,
  "processing_time": 6.214,
  "requests_remaining": 4987
}
```

Поле `requests_remaining` показывает остаток вашей месячной квоты (`-1` означает безлимит).

## Стриминг сводки

Для длинных документов или интерактивных приложений вы можете получать сводку потоком по мере ее генерации:

```python
import json

def stream_summary(path):
    with open(path, "rb") as f:
        with requests.post(
            API_URL + "?stream=1",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"file": (os.path.basename(path), f, "application/pdf")},
            data={"length": "long", "format": "mixed"},
            stream=True, timeout=300,
        ) as resp:
            resp.raise_for_status()
            for line in resp.iter_lines(decode_unicode=True):
                if not line or not line.startswith("data: "):
                    continue
                payload = line[6:]
                if payload == "[DONE]":
                    break
                event = json.loads(payload)
                if "error" in event:
                    raise RuntimeError(event["error"])
                if event.get("type") == "summary":
                    print(event["content"], end="", flush=True)

stream_summary("research-paper.pdf")
```

## Пакетная обработка папки с PDF

```python
import pathlib, time

out_dir = pathlib.Path("summaries")
out_dir.mkdir(exist_ok=True)

for pdf in sorted(pathlib.Path("pdfs").glob("*.pdf")):
    target = out_dir / (pdf.stem + ".md")
    if target.exists():
        continue                      # удобно для возобновления
    for attempt in range(3):
        try:
            data = summarize_pdf(str(pdf), length="long", fmt="mixed")
            target.write_text(data["summary"], encoding="utf-8")
            print("готово", pdf.name, data["page_count"], "стр.")
            break
        except RuntimeError as e:
            if str(e).startswith("429"):
                time.sleep(30 * (attempt + 1))   # превышен лимит: ждем перед повтором
            else:
                print("ошибка", pdf.name, e)
                break
```

## Возможные ошибки

| Статус | Значение | Что делать |
|---|---|---|
| 400 | Файл не передан, неверный тип, превышен лимит страниц | Проверьте файл и лимит страниц вашего тарифного плана |
| 401 | Отсутствует или недействителен ключ API | Проверьте заголовок `Authorization` |
| 403 | Аккаунт заблокирован | Обратитесь в службу поддержки |
| 413 | Файл слишком большой | Сжатите или разделите PDF-файл |
| 422 | Нет читаемого текста (пустой файл, защита или нечитаемый скан) | Удалите пароль; улучшите качество сканирования |
| 429 | Превышен лимит запросов или месячная квота | Подождите и повторите запрос или обновите тариф |
| 500 | Функция суммирования временно недоступна | Повторите запрос позже с задержкой |

> **Хотите протестировать без написания кода?** — Попробуйте этот движок бесплатно в браузере.

## Советы

- **Задавайте таймауты** с запасом (2–3 минуты) для обработки больших PDF-файлов.
- **Кэшируйте результаты** по хэшу файла, чтобы не платить дважды за обработку одного и того же документа.
- **Храните ключи на сервере** — никогда не встраивайте их во фронтенд или мобильные приложения.
- Полный справочник параметров доступен в [документации по API](/docs).

## FAQ

### Доступен ли бесплатный тариф API?

Да. Бесплатный тариф включает месячную квоту запросов без необходимости указывать данные кредитной карты. См. страницу тарифов.

### Можно ли передать URL вместо файла PDF?

API принимает сам файл. Скачайте PDF в своем коде (например, с помощью requests) и отправьте его байты.

### На каких языках можно получить сводку?

Используйте параметр outputLang=auto, чтобы сохранить язык исходного документа, или укажите код языка, например en, fr, es, de.

### Как обрабатывать сканированные PDF-файлы через API?

Отправляйте их так же, как любые другие PDF: если текстовый слой отсутствует, система автоматически задействует OCR-распознавание.

---
Source: https://pdf-summarize.com/ru/guides/pdf-summary-api-python — PDF Summarizer (free PDF summarizer, Q&A with page citations, OCR, REST API). Site overview: https://pdf-summarize.com/llms.txt