| name | kz-academy |
| description | Используй этот скилл, когда пользователь работает с любым API из RapidAPI Hub — формирует HTTP-запросы, разбирается с заголовками авторизации (X-RapidAPI-Key, X-RapidAPI-Host), отлаживает ошибки 401/403/429, спрашивает про стоимость/тарифы/квоту RapidAPI, упоминает конкретный коннектор (yt-api, telegram-channel, threads-api4, tiktok-api23, instagram-looter2, weather, translate и т.п.), строит контент-завод/виральный анализ/мониторинг блогеров/транскрипцию и переписывание скриптов на базе этих коннекторов, выбирает LLM-модель (Claude/GPT/Gemini/DeepSeek через OpenRouter) под задачу или сравнивает их по цене, или запускает все сервисы (Whisper, S3, Telegram Bot, PostgreSQL) для полного pipeline. Скилл содержит общие правила работы с RapidAPI, расчёт расходов по тарифным планам, карточки коннекторов с верифицированными тарифами, готовые методологии контент-завода (docs/methodology/), сравнение 367+ LLM-моделей с verified ценами OpenRouter, и пошаговый full-stack setup всех необходимых сервисов (docs/full-stack-setup.md). |
RapidAPI Helper
Скилл помогает правильно работать с любым коннектором из RapidAPI Hub. Состоит из двух уровней: общие правила (этот файл) и карточки конкретных коннекторов в connectors/.
Как пользоваться
- Прочитай раздел "Общие правила" ниже — они одинаковы для всех коннекторов RapidAPI.
- Определи, о каком коннекторе спрашивает пользователь.
- Открой соответствующий файл из
connectors/. Если его нет — действуй по общим правилам и предупреди, что специфика коннектора не задокументирована.
- Если пользователь начинает с нуля (нет ключа, нет подписки на коннектор) — сначала направь его на docs/getting-started.md. Без этого первого шага любые вызовы вернут 401 или 403.
- Если пользователь спрашивает про подключение к конкретному ИИ-инструменту — открой соответствующий
docs/installation-*.md (есть варианты для Claude Code, Cursor, Claude.ai, ChatGPT, MCP-клиентов, прямого API, и любого generic-LLM).
Перед первым запросом — обязательная подписка
⚠️ Самая частая ошибка новичков: один API-ключ RapidAPI работает со всеми API в каталоге, но для каждого API нужна отдельная подписка. Без подписки любой вызов вернёт 403 You are not subscribed to this API.
Алгоритм: открой страницу нужного коннектора (ссылка Subscribe (Pricing) есть в каждой карточке) → выбери план (обычно начинают с Basic = $0) → нажми Subscribe. RapidAPI потребует привязать карту даже для бесплатного плана — это не списание, а защита от абуза.
Общие правила RapidAPI
Авторизация
Все запросы к RapidAPI требуют двух заголовков:
X-RapidAPI-Key: <твой ключ из dashboard>
X-RapidAPI-Host: <host коннектора, например yt-api.p.rapidapi.com>
X-RapidAPI-Host всегда совпадает с доменом из base URL коннектора. Если забыть его — получишь 403 Forbidden, даже если ключ верный. Это самая частая ошибка новичков.
Базовая структура запроса (Python)
import os
import requests
url = "https://<host>/<endpoint>"
headers = {
"X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
"X-RapidAPI-Host": "<host>",
}
params = {...}
response = requests.get(url, headers=headers, params=params, timeout=15)
response.raise_for_status()
data = response.json()
Никогда не хардкодь ключ в код. Используй .env или переменные окружения.
В этом репозитории есть готовая обвязка — см. examples/common.py. Она сама читает RAPIDAPI_KEY, добавляет ретраи и кэширование.
Типичные ошибки
| Код | Причина | Что делать |
|---|
| 401 | Нет ключа или ключ неверный | Проверить X-RapidAPI-Key |
| 403 | Не подписан на API или нет X-RapidAPI-Host | Подписаться на free-план в RapidAPI; добавить host-заголовок |
| 429 | Превышен rate limit или квота | Подождать; проверить план; кэшировать ответы |
| 5xx | Проблема на стороне провайдера | Ретрай с backoff; написать в discussions провайдера |
⚠️ Многие провайдеры RapidAPI возвращают 200 OK с ошибкой в теле ({"status": "fail", ...} или {"error": "..."}). Всегда проверяй тело ответа перед использованием — response.raise_for_status() тут не поможет.
Пагинация
Большинство списочных эндпоинтов используют continuation-токены: в ответе приходит continuation (или token/nextPageToken/cursor), который надо передать обратно в следующем запросе как параметр token (или одноимённый). Если поле отсутствует/пустое — страниц больше нет. Конкретное имя поля смотри в карточке коннектора.
JSON-структура ответов
У большинства коннекторов:
- список элементов лежит в
data: [...];
- у элементов есть
type — фильтруй по нему, в одной выдаче часто перемешан разный контент;
- поля могут пропадать между релизами провайдера. Всегда используй
.get(key, default) вместо прямого обращения.
Rate limits
У каждого коннектора свои лимиты, которые зависят от плана (BASIC/PRO/ULTRA/MEGA). На free-плане часто стоит лимит вроде "500 запросов в месяц" и "5 запросов в секунду". Всегда проверяй вкладку Pricing на странице коннектора, прежде чем писать продакшн-код.
Кэширование
Большинство запросов к RapidAPI детерминированы (одинаковый запрос → одинаковый ответ в течение какого-то времени). Кэшируй ответы локально, чтобы не сжигать квоту в разработке.
import requests_cache
session = requests_cache.CachedSession("rapidapi_cache", expire_after=3600)
Расчёт расходов (важно для AI-ассистента)
Когда пользователь спрашивает "сколько это будет стоить?" или собирается строить что-то на RapidAPI — обязательно прикинь расходы заранее, до того как он начнёт писать код. Тарифные планы и стоимость отдельных параметров для каждого коннектора лежат в его карточке connectors/<имя>.md в разделе "Тарифы и расчёт расходов".
Универсальная формула
quota_per_request = 1 + sum(модификаторов с пометкой "+1 квота")
month_quota_usage = quota_per_request × запросов_в_месяц
month_bandwidth_mb = средний_размер_ответа_MB × запросов_в_месяц
# Подбор плана (см. таблицу планов в карточке коннектора):
plan = первый план, где month_quota_usage ≤ запросов/мес плана
# Bandwidth (если коннектор отдаёт большие данные — видео, файлы):
extra_mb = max(0, month_bandwidth_mb - bandwidth_включённый_в_план)
bandwidth_cost = extra_mb × цена_за_1MB
total_monthly = plan_price + bandwidth_cost
Что обычно даёт +1 квоты на запрос (зависит от коннектора, точные правила в карточке)
- Доп. флаги расширенного ответа (
extend=1, extend=2, details=full и т.п.)
- Альтернативные идентификаторы (handle вместо id, slug вместо id)
- Локализация (
local=1, localized=true)
- Принудительный refresh кэша (
X-CACHEBYPASS, nocache=1)
- Multi-id batch (+1 за каждый дополнительный id)
- Пропущенные обязательные гео-параметры (если коннектор штрафует за это)
Что выяснить у пользователя перед расчётом
- Сколько запросов в день/час? — Это первое, без чего ничего не считается.
- Какие эндпоинты будет вызывать? — Каждый имеет свою стоимость.
- Нужны ли расширенные данные (
extend=1 и т.п.)? — Это умножает стоимость.
- Будет ли скачивать большие файлы (видео, аудио, PDF)? — Тогда главный расход не в квоте, а в bandwidth.
- Это разовая задача или регулярная? — Для разовой — Basic + кэш, для регулярной — нужен план повыше.
Что обязательно сказать пользователю
- Конкретную сумму в долларах/месяц с разбивкой
$X (план) + $Y (bandwidth) = $Z.
- Какой план достаточен и почему.
- Способы сэкономить (кэш, multi-id, отказ от ненужных модификаторов).
- Предупреждение про rate limit (количество запросов в час/секунду — отдельно от месячного лимита).
- Предупреждение про hard limit vs overage — на большинстве планов RapidAPI hard limit (после превышения — 429), на некоторых старших планах есть overage по фиксированной цене.
Пример рассуждения
Пользователь хочет мониторить просмотры 500 видео каждые 10 минут.
500 × (60/10 = 6 раз/час) × 24 × 30 = 2 160 000 запросов/мес.
Если использовать /video/info — это 2.16M units, Pro ($51) маловато (1.77M), нужен Ultra ($144).
Но /updated_metadata поддерживает multi-id (10 за раз) — тогда 216 000 запросов × 10 units = те же 2.16M units, но в 6 раз меньше HTTP-вызовов (это снижает риск rate-limit).
Альтернатива — кэш на 5 минут (если данные нужны не моментально): запросов вдвое меньше → Pro ($51) хватит.
Итог: $51-144/мес в зависимости от частоты обновления. Bandwidth в норме — ответы небольшие.
Безопасность
- Ключ RapidAPI — это деньги. Утечёт в публичный репозиторий — кто-то выжжет квоту.
- Добавь
.env в .gitignore сразу.
- Для фронтенда никогда не вызывай RapidAPI напрямую из браузера — только через свой бэкенд.
Доступные коннекторы
| Коннектор | Файл | Что делает |
|---|
| YT-API (ytjar) | connectors/yt-api.md | YouTube: поиск, видео, каналы, плейлисты, тренды, шортсы, комментарии, субтитры, транскрипты, скачивание |
| Telegram Channel (akrakoro) | connectors/telegram-channel.md | Публичные Telegram-каналы: метаданные канала и последние сообщения с медиа |
| Threads API (Lundehund) | connectors/threads-api4.md | Threads (Meta): профили, посты, репосты, ответы, комментарии, поиск (top/recent/profiles) |
| TikTok API (Lundehund) | connectors/tiktok-api23.md | TikTok: пользователи, видео, лайвы, музыка, эффекты, тренды (creator/video/hashtag/song), Ads/Creative Center, скачивание (56 эндпоинтов) |
| Instagram Looter (irrors-apis) | connectors/instagram-looter2.md | Instagram: профили, посты, рилсы, репосты, отмеченные медиа, хэштеги, локации, Explore-лента, поиск (30 эндпоинтов) |
| добавь свой | connectors/<имя>.md | описание |
Готовые методологии контент-завода
Когда пользователь спрашивает не "как сделать запрос к API X", а "как мне построить виральную аналитику / контент-завод / мониторинг блогеров / переписывание скриптов" — это про методологию, не про коннектор. Открывай соответствующий playbook:
| Документ | О чём |
|---|
| docs/methodology/README.md | Индекс всех playbook'ов |
| docs/methodology/pipeline-overview.md | Полный flow: блогер → видео → детект → транскрипция → скрипт. Архитектура очередей. |
| docs/methodology/viral-detection.md | Как отличить виральное от просто популярного: ССН-метрика, baseline, тройной фильтр, готовые числовые пороги. |
| docs/methodology/author-monitoring.md | Расписание опроса (профиль раз в сутки, лента каждый час), что записывать, оптимизации. |
| docs/methodology/transcription-rewriting.md | Whisper/AssemblyAI → LLM-переписывание с готовыми промптами по нишам (edu/comedy/lifestyle/business). |
| docs/methodology/llm-models.md | Сравнение 367+ LLM-моделей через OpenRouter. Бюджет/Стандарт/Премиум tier'ы. Какую модель под какую задачу. Verified цены апрель 2026. |
| docs/methodology/cost-modeling.md | Стоимость одного миллионника, формула "сколько авторов под цель", точки перехода между тарифами. Полная стоимость pipeline (RapidAPI + LLM + Whisper + Storage). |
| docs/full-stack-setup.md | Пошаговая регистрация ВСЕХ сервисов для запуска контент-завода: RapidAPI, OpenRouter, Whisper, S3, Telegram Bot, PostgreSQL, Redis, VPS. Прямые ссылки + что в .env. Бюджеты для Стартапа/SMB/Крупной редакции. |
Эти playbook'и адаптированы из реальных продакшн-систем виральной аналитики и содержат проверенные числовые пороги (множители baseline, окна ССН, частоты опроса). Используй их когда AI-ассистенту задают системный вопрос про архитектуру/детекцию/экономику, а не про конкретный API-вызов.
Как добавить новый коннектор
Через CLI-скрипт:
python scripts/new_connector.py --name "weather-api" --host "weather-api123.p.rapidapi.com"
Или вручную: скопируй connectors/_template.md в connectors/<имя>.md и заполни:
- Имя, провайдер, базовый URL, host-заголовок.
- Список эндпоинтов с параметрами и примерами.
- Особенности: лимиты, типичные ошибки, нюансы ответов.
- Минимум один работающий пример кода.
Чем подробнее карточка — тем точнее ИИ будет помогать с этим коннектором.
