Как использовать Tyver API: полное руководство по автоматизации спай-сервиса ⚙️

Парсинг рекламы Facebook необязательно проводить вручную. Иногда его проще поручить скриптам и алгоритмам, чтобы сэкономить время и силы. Для автоматизированного поиска и сбора рекламы в Tyver есть API-интеграция. 🤖

Что такое Tyver API и какие задачи он решает?

Обычная работа с Тайвер выглядит так: вы открываете спай-сервис, вбиваете запрос, задаете фильтры и получаете выдачу рекламных объявлений.

Поиск рекламы в веб-интерфейсе Tyver

Tyver.io api позволяет все действия по поиску и фильтрации отдать программе, сняв с вас большую часть ручной работы.

💡 Например, каждый день вы ищете гемблинг-креативы по США с сортировкой выдачи по длительности открутки. В рамках API-интеграции можно написать программу, которая сама будет отправлять Tyver запрос с этими параметрами и получать найденные объявления.

Автоматический поиск креативов через Tyver API

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

Выгрузка креативов по API может быть прислана в телеграм-боте, веб-странице или самописной программе. 📲

Варианты вывода креативов из Tyver API

Получить можно не только сам рекламный креатив. API возвращает и другие данные:

  • 📝 Текст объявления;
  • 🌍 Страну показа;
  • 🗣 Язык;
  • 📅 Дату запуска и последней активности;
  • 👤 Фанпейдж;
  • 📍 Плейсменты;
  • 🔗 Целевую ссылку;
  • 🎞 Тип креатива и ссылки на изображения или видео.

🇪🇺 Для части объявлений из ЕС доступны также данные о возрасте и поле аудитории и примерном количестве показов. К тому же API возвращает значения verticals и vertical_subcategories: всего 37 подкатегорий, например конкретные слоты вроде AVIATOR.

Преимущества АПИ перед веб-интерфейсом

⚡ Главное преимущество автоматизации через API: не нужно тратить время на повторяющиеся действия. Один раз настроили шаблон поиска, а затем он работает на вас, пока вы его не отключите.

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

Поиск рекламы интернет-магазинов в США
Результаты поиска интернет-магазинов в Tyver

🔄 Другая ситуация: вы нашли несколько интересных магазинов и вам каждый день нужно смотреть изменения по креативам, которые у них крутятся. Можно, конечно, настроить шаблон поиска по доменам и фанпейдж, но этот шаблон придется каждый день использовать вручную:

  • Заходить на сайт Tyver;
  • Проводить поиск по сохраненному шаблону;
  • Отсматривать самые свежие объявления, а вчерашние игнорировать.

Здесь и появляется смысл в автоматизации через API:

  • Вы настраиваете запрос на поиск по нужным параметрам;
  • Tyver отвечает на этот поиск и возвращает результаты поиска в вашу программу;
  • Программа (если настроена на это) показывает появившиеся сегодня объявления, а также подсвечивает креативы, которые перестали крутиться.

Кроме того, результат поиска сразу доходит до конечного потребителя: например, параметры поиска настраивает маркетолог, а результаты передаются сразу медиабайерам.

Как подключить API Tyver?

🔑 Для начала вам понадобится API key (токен авторизации). Получить его можно на этой странице, но для его получения вы должны иметь аккаунт и быть в нем авторизованы.

Раздел API в аккаунте Tyver

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

Генерация API-ключа в Tyver

Теперь нужно прописать адрес, по которому ваша программа будет обращаться к Tyver, и токен доступа.

Адрес, с которого начинается обращение к публичному API Tyver:

https://api.tyver.io/public/v1

HTTP-заголовок с вашим токеном:

X-Tyver-Authorization: tyv_****

Как проверить работу API Key?

Для проверки используем запрос GET из документации.

Запрос GET /info/me в документации Tyver API

Полный запрос будет выглядеть так:

curl -X GET "https://api.tyver.io/public/v1/info/me" \
  -H "X-Tyver-Authorization: tyv_****(токен доступа)"

В ответ Tyver возвращает информацию о тарифе и оставшемся количестве доступных просмотров:

{
  "detail": "Success",
  "data": {
    "remainder_views": 30000,
    "tariff": "PRO"
  }
}

📊 В данном примере PRO — текущий тариф, а remainder_views: 30000 означает, что у вас осталось 30 000 просмотров объявлений по тарифу. Счетчик сбрасывается в начале следующего платежного периода. Тарифы и лимиты на API Tyver такие же, как и на ручное использование спай-сервиса.

Тарифы и лимиты Tyver

Обзор документации и основных эндпоинтов Tyver API

Все команды и запросы можно найти в документации Tyver API по этой ссылке. Для примера рассмотрим наиболее важные из них.

Метод и эндпоинт Назначение
GET /info/me Проверить тариф и оставшийся лимит
GET /creatives/ Найти креативы по заданным фильтрам
GET /creatives/{provider_id} Получить полные данные конкретного креатива
GET /blacklist/ Получить список заблокированных fanpage
POST /blacklist/ Добавить fanpage в черный список
DELETE /blacklist/ Удалить fanpage из черного списка

Метод означает тип действий:

  • 🔍 GET запрашивает информацию;
  • ➕ POST добавляет;
  • 🗑️ DELETE удаляет.

GET /creatives/ основной инструмент для поиска рекламы

С его помощью ищут и выгружают креативы, а сам запрос работает как поисковая строка и фильтры. Параметры поиска и фильтрации указываются в HTTP-запросе.

Например, можно задать:

  • countries=US
  • media_types=VIDEO
  • languages=en
  • vertical=GAMBLING

Таким образом мы просим найти видео-креативы по гемблингу в США на английском языке.

В GET запросе можно задать любые запросы по поиску и фильтрации, которые доступны в Tyver.

Параметры запроса GET /creatives/ в документации

📦 В ответ приходят текст объявления, GEO, fanpage, CTA, площадки размещения, даты активности, целевая ссылка и медиа. Сами изображения и видео подгружаются в поле media. При желании программа может подгрузить и другие данные: тип, размер и превью файла, и даже ссылку для скачивания.

GET /creatives/{provider_id} помогает получить конкретное объявление

У каждого креатива есть provider_id — уникальный идентификатор объявления со стороны рекламной платформы. Благодаря этому идентификатору можно вытаскивать параметры конкретного креатива:

GET /creatives/1234567890

💾 Допустим, вы нашли креатив и сохранили его ID 1234567890. Сегодня вы хотите посмотреть, продолжает ли он крутиться, сколько еще просмотров получил и т.п.

Вместо того чтобы снова запускать поиск с фильтрами, вы отправляете запрос:

GET /creatives/1234567890

Теперь у вас есть актуальная и свежая инфа по сохраненному объявлению. С помощью GET /creatives/{provider_id} можно решать и другие задачи, например по интеграции с CRM. Т.е. обращаться непосредственно к крео внутри CRM и сразу направлять крео ответственному лицу.

/blacklist/ управляет черным списком

Например, нам надо исключить из выдачи некоторые fanpage. В этом помогут:

  • 📋 Запрос GET /blacklist/ получает текущий список;
  • ➕ Команда POST /blacklist/?fan_page_id=123456 добавляет страницу в блэклист;
  • 🗑️ DELETE /blacklist/?fan_page_id=123456 удаляет ее из черного списка.

🚫 У /creatives/ есть параметр without_blacklist=true, который исключает из результатов поиска креативы от фанпейджей из блэклиста. Можно один раз добавить нежелательного рекламодателя в черный список, чтобы не засорять поиск его рекламой.

Как использовать Tyver API? Пример кода для Telegram-бота

Зная ключевые запросы, напишем код, который делает поиск по Tyver через телеграм-бота по API. 🤖 Для интеграции помимо апи-токена понадобится Telegram Bot Token. Он позволяет отправлять сообщения в Telegram и его можно получить через BotFather.

Создание Telegram-бота через BotFather

🐍 Сам код напишем на Python. Это один из самых простых языков для подобных задач.

Пример рабочего кода

Для начала установим библиотеку requests:

Bash

pip install requests

Теперь создадим файл bot.py и вставим следующий код:

import requests
import time

TYVER_KEY = "tyv_****"
BOT_TOKEN = "ВАШ_TELEGRAM_BOT_TOKEN"
TG_API = f"https://api.telegram.org/bot{BOT_TOKEN}"
TYVER_API = "https://api.tyver.io/public/v1"

offset = 0

while True:
    updates = requests.get(
        f"{TG_API}/getUpdates",
        params={"offset": offset, "timeout": 30},
        timeout=40
    ).json()

    for update in updates.get("result", []):
        offset = update["update_id"] + 1
        message = update.get("message", {})

        if message.get("text") != "/ads":
            continue

        chat_id = message["chat"]["id"]

        response = requests.get(
            f"{TYVER_API}/creatives/",
            headers={"X-Tyver-Authorization": TYVER_KEY},
            params={
                "countries": "US",
                "media_types": "VIDEO",
                "languages": "en",
                "vertical": "GAMBLING"
            },
            timeout=30
        )

        if response.status_code != 200:
            requests.post(
                f"{TG_API}/sendMessage",
                json={"chat_id": chat_id, "text": "Ошибка TYVER API"},
                timeout=30
            )
            continue

        ads = response.json()["data"]["items"][:5]

        for ad in ads:
            text = (
                f"Страница: {ad.get('provider_page_name')}\n"
                f"GEO: {', '.join(ad.get('countries') or [])}\n"
                f"Текст: {(ad.get('bodies') or [''])[0][:500]}\n"
                f"ID: {ad['provider_id']}"
            )
            requests.post(
                f"{TG_API}/sendMessage",
                json={"chat_id": chat_id, "text": text},
                timeout=30
            )

    time.sleep(1)

Запускаем командой:

Bash

python bot.py

🚀 Теперь открываем созданного Telegram-бота и отправляем /ads.

В ответ бот присылает креатив.

Как работает код?

Весь процесс можно объяснить пятью действиями.

  1. Когда пользователь отправляет /ads, начинается поиск.
  2. Отправляет GET-запрос в Tyver. В запросе указаны фильтры countries=US, media_types=VIDEO, languages=en и vertical=GAMBLING.
  3. Tyver возвращает JSON. В нем содержатся найденные креативы и их характеристики.
  4. Python выбирает первые пять объявлений. За это отвечает часть кода [«items»][:5]. Она не ограничивает число объявлений, полученных от API, а выбирает пять из уже полученного списка.
  5. Бот отправляет результаты в Telegram. Для каждого креатива он создает отдельное сообщение с названием рекламной страницы, GEO, текстом и ID объявления.

✅ Теперь пользователю не нужно открывать Tyver, выставлять фильтры и вручную копировать найденные креативы. Достаточно отправить боту команду /ads.

Ответ Telegram-бота с креативами из Tyver
‼️ ВАЖНО! Этот пример — минимальная и очень сырая демонстрация интеграции, а не готовый бот для круглосуточной работы. Он только обрабатывает команду /ads и только в вертикали гемблинга. Для реальной работы понадобится добавить обработку сетевых ошибок, починить отображение целевых ссылок, сделать поиск по ключевикам и фильтрам, а также много других команд.

Как использовать Tyver API? Пример Желтого Веба

🎯 Арбитражной команде нужно минимизировать ручной поиск. Задача: скрипт должен каждое утро присылать креативы по гемблингу, а байеры сами будут отбирать среди них подходящие.

⏰ Каждое утро по таймеру запускается контроллер. Он читает задания и ограничения конкретного прогона.

Настройки заданий контроллера в кейсе Yellow Web

Операторы работают следующим образом:

  • top задает нужное количество креативов по каждому заданию;
  • В refill.mode выбираем режим добора (выключен, запускается вручную или включается после отказов валидатора);
  • min_impressions останавливает добор, когда показы опускаются ниже установленного порога;
  • max_checked ограничивает общее число просмотренных карточек.

Дата задания превращается в точный диапазон API: creation_date_gte=2026-07-27 и creation_date_lte=2026-07-27. Дальше работа идет по шагам:

  • 1️⃣ Обычный worker вызывает Tyver CLI и получает до 60 карточек по каждому заданию;
  • 2️⃣ Tyver сортирует объявления по убыванию показов. Worker берет первые десять;
  • 3️⃣ Код отбрасывает точные дубли и ищет похожие файлы во внутренней базе. Для уже знакомых креативов подтягиваются прошлые решения команды;
  • 4️⃣ Агент-валидатор ставит accept, review или reject и объясняет решение;
  • 5️⃣ Принятые карточки попадают в галерею. Спорные уходят на проверку человеку.

Если для задания включен добор после отказов валидатора, контроллер берет следующие карточки из уже загруженной выдачи. В обычном запуске этот режим выключен.

🗄️ Внутренняя база начинает копиться с первого прогона. В ней сохраняются карточки, файлы и решения баеров. Точный дубль увеличивает счетчик перезаливов у существующей карточки. Для похожего креатива система показывает прошлую разметку, если команда уже успела ее добавить.

Интерфейс с креативами, собранными через Tyver API

Рабочий интерфейс, в который Tyver API возвращает собранные креативы.

📖 Читать полный кейс с ценными деталями в источнике.

Частые ошибки при работе с Tyver API и методы их решения

🛠 Код для работы с Тайвером по АПИ не всегда запускается с первой попытки. Иногда он может выдавать ошибки. Рассмотрим наиболее вероятные из них, которые указаны в документации.

Ошибка 401. Проблема с API Key

🔐 401 Unauthorized означает, что Tyver не смог авторизовать запрос. Чаще всего причина в отсутствующем, неправильном или недействительном API Key.

Стоит проверить две вещи: сам токен и название заголовка. Tyver требует передавать ключ именно так:

X-Tyver-Authorization: tyv_****

После настройки ключа сначала выполните запрос GET /info/me. Если этот запрос успешно возвращает тариф и remainder_views, авторизация работает и проблему в остальных запросах следует искать уже не в API Key.

Ошибка 403. Нет доступа к API или закончился лимит просмотров

⛔ 403 Access denied возникает в двух случаях: эндпоинт недоступен на текущем тарифе либо исчерпан лимит на просмотры креативов.

Чтобы минимизировать вероятность этой ошибки:

  • 1️⃣ До запуска автоматизации проверьте GET /info/me;
  • 2️⃣ Сделайте один тестовый поиск;
  • 3️⃣ Снова проверьте /info/me.

Так вы увидите, сколько просмотров списано, и примерно оцените, насколько вам хватит лимита. Заодно вы сможете отсечь лишние объявления и просто не будете их выгружать, чтобы не тратить на них доступное число просмотров.

Ошибки 400 и 422 — неправильно составлен запрос

⚙️ Еще одна распространенная проблема — сами параметры поиска. Например, API ожидает определенные значения:

  • media_types=VIDEO
  • vertical=GAMBLING
  • creation_date_gte=2026-09-01

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

Особенно внимательно стоит работать со значениями, перечисленными в документации. Например, типы креативов имеют конкретные обозначения IMAGE, VIDEO и CAROUSEL, а доступные площадки: facebook, instagram, audience_network, messenger, whatsapp, oculus и threads.

Ошибка 400 Bad Request отдельно предусмотрена, например, для некорректного cursor. Поэтому курсор следующей страницы лучше не создавать и не изменять самостоятельно. Нужно брать ровно то значение, которое Tyver вернул в предыдущем ответе.

В заключение

Настоящие преимущества Tyver API показывает в работе с большими объемами данных и при регулярном однообразном поиске. Если вы пару раз в день самостоятельно ищете креативы, веб-версия будет удобнее.

🚀 Но если вы каждый день отслеживаете рекламодателей, выгружаете сотни креативов для адаптации, Tyver API сэкономит много времени на ручных повторяющихся операциях.

Инструмент необходим не только в арбитраже трафика, но и в интернет-маркетинге, SMM и даже в социологических исследованиях, связанных с пользовательскими предпочтениями.

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

FAQ

❓ Где взять API Key для работы с Tyver?

Получить токен можно в разделе Аккаунт → API. Вот ссылка для быстрого доступа в этот раздел.

❓ Доступен ли Tyver API на бесплатном (триал) тарифе?

Нет, для API-интеграции необходим платный тариф PRO или Team.

❓ Каковы лимиты на количество запросов в минуту?

Лимит на число запросов в минуту не предусмотрен. Есть лимит на количество просмотров объявлений в месяц: для тарифа PRO до 30 тысяч и для Team до 60 тысяч. Соответственно, если вы исчерпаете лимит на количество просмотров, запросы станут недоступны до начала следующего оплаченного периода.

❓ Можно ли через API скачивать оригинальные видео-креативы Facebook?

Да, в ответе API в поле media приходят ссылки на файлы изображений и видео, а также их превью.

❓ На каких языках программирования можно использовать API Tyver?

Можно работать на любом языке программирования, который умеет отправлять HTTP-запросы: Python, JavaScript, PHP, Java, C#, Go и др.