kz-academy

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/.

Как пользоваться

1. Прочитай раздел "Общие правила" ниже — они одинаковы для всех коннекторов RapidAPI.
2. Определи, о каком коннекторе спрашивает пользователь.
3. Открой соответствующий файл из connectors/. Если его нет — действуй по общим правилам и предупреди, что специфика коннектора не задокументирована.
4. Если пользователь начинает с нуля (нет ключа, нет подписки на коннектор) — сначала направь его на docs/getting-started.md. Без этого первого шага любые вызовы вернут 401 или 403.
5. Если пользователь спрашивает про подключение к конкретному ИИ-инструменту — открой соответствующий 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 = {...}  # query-параметры эндпоинта

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)
• Пропущенные обязательные гео-параметры (если коннектор штрафует за это)

Что выяснить у пользователя перед расчётом

1. Сколько запросов в день/час? — Это первое, без чего ничего не считается.
2. Какие эндпоинты будет вызывать? — Каждый имеет свою стоимость.
3. Нужны ли расширенные данные (extend=1 и т.п.)? — Это умножает стоимость.
4. Будет ли скачивать большие файлы (видео, аудио, PDF)? — Тогда главный расход не в квоте, а в bandwidth.
5. Это разовая задача или регулярная? — Для разовой — 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 и заполни:

1. Имя, провайдер, базовый URL, host-заголовок.
2. Список эндпоинтов с параметрами и примерами.
3. Особенности: лимиты, типичные ошибки, нюансы ответов.
4. Минимум один работающий пример кода.

Чем подробнее карточка — тем точнее ИИ будет помогать с этим коннектором.