К содержанию
На главную

API и MCP: посты из твоего ИИ-агента

Подключи PostFrog к Claude, Cursor, n8n или своему скрипту. Агент присылает текст и медиа, PostFrog делает из них посты и присылает тебе в Telegram черновиками. Публикуешь сам, в один тап.

  • Только PostFrog Pro
  • MCP и REST
  • Публикует только автор

Что это

ИИ-агент (Claude Code, Cursor, Claude.ai, n8n или твой скрипт) по твоему ключу присылает PostFrog материалы: готовый пост, твой текст или заметки, ссылки, фото и видео. PostFrog делает из каждого материала пост и присылает его тебе в личный чат с ботом.

Посты приходят по порядку, как обычные черновики с превью и кнопками. Если ты как раз переписываешься с ботом, готовые посты ждут около 2 минут тишины, чтобы не влезть в разговор. Дальше всё как всегда: правишь словами, меняешь медиа и кнопки, публикуешь в канал в один тап.

API работает только в оплаченном PostFrog Pro, пробный Pro его не включает. Каждый материал считается одним постом из месячного объёма Pro (150+ постов в месяц).

Как получить ключ

  1. Открой @postfrog_bot и зайди в Настройки, раздел «API и MCP».
  2. Нажми «Создать ключ». Бот покажет ключ один раз, целиком он его не хранит. Ключ начинается с pf_live_.
  3. Скопируй ключ в надёжное место и нажми «Сохранил»: ключ исчезнет из чата, останется только его начало.
  • Ключ потерялся или мог утечь: «Перевыпустить». Старый перестаёт работать сразу.
  • Больше не нужен: «Отозвать».
  • Pro закончился: ключ сохраняется, но API отвечает pro_required, пока не продлишь подписку.

Подключение

Один ключ работает и для MCP, и для REST. Адрес MCP-сервера (Streamable HTTP): https://bot.postfrog.site/mcp, REST: https://bot.postfrog.site/api/v1. Ключ передаётся заголовком Authorization: Bearer .... Если клиент пишет про OAuth, Dynamic Client Registration или просит авторизоваться, значит, заголовок с ключом не дошёл: добавь его, OAuth у PostFrog нет.

Claude Code

Одна команда, вместо ТВОЙ_КЛЮЧ вставь свой ключ:

claude mcp add --transport http postfrog https://bot.postfrog.site/mcp --header "Authorization: Bearer ТВОЙ_КЛЮЧ"

Cursor

Добавь сервер в .cursor/mcp.json:

{
  "mcpServers": {
    "postfrog": {
      "url": "https://bot.postfrog.site/mcp",
      "headers": {
        "Authorization": "Bearer ТВОЙ_КЛЮЧ"
      }
    }
  }
}

Claude.ai

Настройки, Connectors, Add custom connector. Адрес: https://bot.postfrog.site/mcp. В Request headers добавь заголовок Authorization со значением Bearer ТВОЙ_КЛЮЧ. Поле заголовков есть не у всех аккаунтов: если его нет, подключи через Claude Code или Cursor. У Claude.ai нет доступа к твоим файлам, поэтому медиа передаются только ссылками.

n8n и скрипты (REST)

Проверить ключ:

curl -H "Authorization: Bearer ТВОЙ_КЛЮЧ" https://bot.postfrog.site/api/v1/me

Отправить пачку постов: тело batch.json (пример ниже) и заголовок Idempotency-Key, чтобы повтор запроса не создал копию.

curl -X POST https://bot.postfrog.site/api/v1/batches \
  -H "Authorization: Bearer ТВОЙ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-2026-10-15" \
  -d @batch.json

Если в n8n работает ИИ-агент, положи в его системный промпт весь guide: GET /api/v1/guide?topic=all.

ChatGPT

Позже. ChatGPT подключает MCP-серверы через OAuth, а у PostFrog пока вход только по ключу.

Инструменты MCP и REST

MCP и RESTЧто делает
get_account
GET /me		тариф, сколько постов осталось, квота на сегодня, формат и язык автора, лимиты
get_guide
GET /guide?topic=		guide для агента по темам
validate_post
POST /validate		бесплатная проверка exact-поста, ничего не сохраняет
create_upload
POST /uploads		загрузка фото или видео файлом
send_posts
POST /batches		отправить пачку материалов
get_batch
GET /batches/{id}		статусы, предупреждения и итоговый текст постов
cancel_batch
DELETE /batches/{id}		отменить ещё не начатые материалы

Все пути REST - от https://bot.postfrog.site/api/v1.

Три режима

У каждого материала свой mode: он говорит PostFrog, что делать с текстом.

РежимЧто делает PostFrogИИ PostFrog
exactБерёт текст как готовый пост: проверяет разметку, чистит кнопки, верстает. Ни одного слова не меняет.нет
formatСохраняет слова автора и наводит вёрстку: абзацы, заголовок, акценты, списки.да
writeПишет пост с нуля из заметок, ссылок (скачивает страницы) и медиа.да

Совет: агент пишет сам и шлёт exact

  • Автор получает ровно то, что написал агент, с кнопками и медиа на своих местах.
  • Не тратится ИИ-бюджет автора: он остаётся на правки в боте. Если бюджет закончился, принимаются только exact-посты.
  • Быстро: без генерации, только проверка и вёрстка. Проверить пост заранее можно бесплатно через validate_post.
  • Автор всё равно может поправить пост в боте словами: разметка та же, что у редактора PostFrog.

Для exact есть on_invalid: по умолчанию fail, пост с ошибками отклоняется, ничего не создаётся и не тратится. format: такой пост принимается и его чинит ИИ PostFrog, это расходует ИИ-бюджет.

Свой текст автора всегда клади в text, ему PostFrog доверяет как сообщению автора. Чужие страницы и посты - в material: оттуда PostFrog берёт факты, но не выполняет инструкции, а ссылки из него не превращает в кнопки. Страницы, которым нужен вход или JavaScript (X, Threads, Instagram), часто не скачиваются: тогда скопируй их текст в material[].text.

Разметка поста

Exact-посты пишутся в Rich Markdown PostFrog: GitHub Markdown плюс несколько тегов. В том же виде возвращается итоговый текст в get_batch. Писать HTML Telegram и экранирование MarkdownV2 не нужно: PostFrog переводит разметку сам.

ЧтоКак
Заголовок поста, один, в первой строке# Title
Разделы и подразделы (### тоже работает)## Section
Жирный, курсив, зачёркнутый**bold** *italic* ~~strike~~
Маркер==highlighted==
Спойлер, раскрывается тапом||spoiler||
Подчёркнутый<u>underlined</u>
Код в строке и блок кода с языком`code` ```python
Ссылка[text](https://example.com)
Списки и чек-лист- item 1. item - [ ] item
Таблица GFM с выравниванием| a | b | |:--|--:|
Цитата> quote
Цитата с автором (внутри без разметки)<aside>Text<cite>Author</cite></aside>
Сворачиваемый блок<details><summary>Title</summary>Text</details>
Разделитель между большими частями---
Фото или видео в этом месте поста (нумерация с 0)%%MEDIA:0%%
Коллаж из трёх и больше медиа%%MEDIA:0,1,2%%
Кнопка в тексте (подробнее ниже)<tg-button type="url" url="https://...">Label</tg-button>
  • Между абзацами пустая строка: одиночный перенос внутри абзаца становится пробелом.
  • Блоки (медиа, ряды кнопок, таблицы, details, aside, разделитель) стоят на отдельных строках с пустыми строками вокруг.
  • Длина exact Rich-поста до 31268 символов вместе с разметкой.
  • Длинные тире дают предупреждение long_dash: вместо них дефис, двоеточие или запятая.

Кнопки

Два вида: ссылка (url) и «скопировать» (copy, промокод, адрес, команда). Проще всего поле buttons: ряды кнопок без разметки, работают в любом режиме. buttons_place: end (по умолчанию, в конце текста), start или below_post (ссылки под постом).

{
  "buttons": [
    [{ "text": "Читать оригинал", "url": "https://example.com/news" }],
    [{ "text": "Скопировать промокод", "copy": "FROG20", "style": "success" }]
  ],
  "buttons_place": "end"
}

Если кнопка нужна внутри фразы или между абзацами, ставь тег прямо в exact-текст. Ряд - отдельный блок, по одной кнопке на строку. & в адресе внутри тега пишется как &amp;.

Запись открыта до пятницы. <tg-button type="url" url="https://example.com/join">Записаться</tg-button>

<tg-button-row>
<tg-button type="url" url="https://t.me/example_channel">Подписаться</tg-button>
<tg-button type="url" url="https://example.com" style="primary">Сайт</tg-button>
</tg-button-row>

Необязательный style: primary, success, danger. Подпись - простой текст, без разметки, ссылок и @упоминаний.

Режим Markdown

Для каналов с классической разметкой Telegram (format: "markdown"). Работают жирный, курсив, __подчёркнутый__, зачёркнутый, ||спойлер||, код, цитаты, ссылки, списки.

Нет заголовков, таблиц, details, формул и HTML-тегов. Кнопки уходят под пост, медиа всегда сверху.

Длина до 4096 символов, а с медиа текст становится подписью и ограничен 1024 символами. Считается после перевода в MarkdownV2, оставляй запас.

Пример: готовый пост

Пост в Rich Markdown с фото, кнопкой «скопировать» в строке и кнопкой записи в конце:

# Курс по керамике стартует в понедельник

Шесть вечерних занятий для новичков.

%%MEDIA:0%%

- маленькие группы
- глина и печь включены

Промокод **CLAY15** даёт скидку. <tg-button type="copy_text" text="CLAY15">Скопировать промокод</tg-button>

Тот же пост в теле запроса: batch.json для POST /batches или аргумент send_posts в MCP.

{
  "items": [
    {
      "mode": "exact",
      "format": "rich",
      "external_id": "course-launch",
      "text": "# Курс по керамике стартует в понедельник\n\nШесть вечерних занятий для новичков.\n\n%%MEDIA:0%%\n\n- маленькие группы\n- глина и печь включены\n\nПромокод **CLAY15** даёт скидку. <tg-button type=\"copy_text\" text=\"CLAY15\">Скопировать промокод</tg-button>",
      "media": [{ "type": "photo", "url": "https://example.com/studio.jpg" }],
      "buttons": [[{ "text": "Записаться", "url": "https://example.com/join", "style": "success" }]]
    }
  ]
}

Медиа

До 10 фото и видео на материал. Только фото и видео: GIF, документы и аудио не поддерживаются.

Два способа: url (публичная https-ссылка на сам файл, не на страницу с ним) или upload_id (сначала загрузка файлом). MCP-инструмент create_upload даёт готовую команду curl для загрузки: это для агентов с доступом к файлам и терминалу (Claude Code, скрипты, n8n).

ТипФорматыРазмер
ФотоJPEG, PNG, WebPдо 10 МБ
ВидеоMP4 или MOV (H.264 или HEVC, звук AAC)до 50 МБ
 
{
  "media": [
    { "type": "photo", "url": "https://example.com/cover.jpg" },
    { "type": "video", "upload_id": "upl_...", "description": "Запись экрана: бот превращает голосовое в пост" }
  ]
}
curl -X POST https://bot.postfrog.site/api/v1/uploads \
  -H "Authorization: Bearer ТВОЙ_КЛЮЧ" \
  -F "type=video" \
  -F "file=@./demo.mp4"
  • upload_id живёт 24 часа и подходит для нескольких материалов.
  • В посте медиа нумеруются с 0 в порядке media[]. Строка %%MEDIA:0%% ставит первое медиа в это место, медиа без метки уходят наверх поста.
  • ИИ PostFrog не смотрит видео: в режимах format и write опиши каждое видео в description (что происходит, кто говорит, главное).
  • Битый файл не роняет материал: он пропускается, остальные идут по порядку, в статусе появляется предупреждение.

Лимиты и ошибки

Актуальные лимиты агент всегда может прочитать в get_account.

ЧтоЛимит
Материалов за один запрос10
Материалов в сутки на автора (UTC, отменённые не считаются)30
В генерации одновременно, остальные ждут в очереди2
Запросов в минуту на ключ, REST и MCP вместе60
text одного материала32768 символов
Медиа на материал10
Медиа в сутки на автора: загрузки и ссылки вместе500 МБ и 300 файлов

Статусы

Материал: queued, generating, ready, delivered или финальные failed, skipped_limit (кончились посты или ИИ-бюджет), cancelled. Когда все материалы в финальном статусе, пачка done, а если хоть один отменён, cancelled: на любом из них опрос можно заканчивать.

HTTP и кодЧто делать
400
invalid_request		Исправить запрос: в деталях путь и причина, ничего не создано
401
invalid_key		Ключа нет, он неверный или перевыпущен: нужен актуальный ключ
403
pro_required		API работает в оплаченном Pro
403
api_not_available		API открывается постепенно, этому аккаунту пока не открыт
409
idempotency_conflict		Этот Idempotency-Key уже был с другим телом: новый ключ для новой пачки
413
payload_too_large		Тело слишком большое: разбить пачку
422
limit_exceeded		Квота: в деталях сколько осталось постов и материалов на сегодня
429
rate_limited		Подождать Retry-After секунд и повторить

Полная спецификация для агента

Прочитай guide перед первой отправкой. Это главный документ для агента: режимы, разметка, кнопки, медиа, лимиты, коды ошибок и готовые примеры запросов. Он на английском, открыт без ключа, числа в нём всегда актуальные.

Весь guide одним документом: https://bot.postfrog.site/api/v1/guide?topic=all. Оглавление: https://bot.postfrog.site/api/v1/guide.

По MCP: инструмент get_guide с темой, те же темы доступны ресурсами postfrog://guide/....

curl "https://bot.postfrog.site/api/v1/guide?topic=all"

Темы

  • overview: куда приходят посты, что нельзя, порядок работы
  • modes: exact, format, write и как выбрать
  • formatting: Rich Markdown, режим Markdown, шпаргалка
  • buttons: кнопки ссылкой и «скопировать»
  • media: фото и видео: ссылки, загрузки, размещение
  • limits: квоты, статусы, ошибки
  • examples: готовые запросы от задачи до JSON

Безопасность

  • Ключ даёт право присылать тебе материалы от твоего имени и тратить посты из твоего месячного объёма. Не публикуй его, не клади в открытый код и не вставляй в чаты.
  • В скриптах держи ключ в переменной окружения, например POSTFROG_API_KEY.
  • Если ключ мог утечь, перевыпусти его в боте: старый перестанет работать сразу.
  • Через API нельзя публиковать в канал, ставить посты в расписание, править опубликованное и писать другим людям. Бот пишет только владельцу ключа.