Как настроить ИИ-агента для работы с API

Как настроить ИИ-агента для работы с API Вайб-Маркетолога так, чтобы он делал работу, не тратил лишнего и не ломался на первой же ошибке — разбираем по шагам. К концу урока у вас будет ключ с правильными правами, потолок расходов на сутки, понимание, как агент должен вести себя при сбоях, и способ забирать результаты без бесконечных опросов. Всё, что нужно от вас — аккаунт в кабинете и 20 минут.

lk.vibemarketolog.ru/#agent

Что это и когда использовать

API для ИИ-агентов — это способ дать вашему агенту руки. Сам по себе языковой агент умеет рассуждать и писать текст, но не умеет нарисовать баннер, озвучить ролик, собрать сайт или проверить частотность запросов в Яндексе. Через API он получает доступ к 170+ моделям платформы и делает это сам, без вашего участия в каждом шаге.

Два пути подключения, и выбор между ними зависит от того, пишете ли вы код:

• Коннектор для Claude и ChatGPT. Программировать не нужно: вставляете ссылку в настройках чат-бота и дальше просто просите словами — «нарисуй три креатива для рекламы кофейни». Подходит, если вы работаете в чате и хотите, чтобы у ассистента появились новые умения.
• Прямое обращение к API. Для своих скриптов, сервисов и самописных агентов: полный набор методов, вебхуки, собственная логика. Подходит, если вы встраиваете генерацию в свой продукт или автоматизируете рутину пачками.

Когда это точно нужно. Если вы делаете один баннер в неделю — заходите в кабинет руками, API не нужен. Если у вас двадцать товаров и для каждого нужны фото в трёх ракурсах, или вы каждое утро собираете отчёт по рекламе, или у вас уже есть агент, который ведёт клиентские проекты — вот здесь API экономит часы.

Для кого этот инструмент

Маркетолог-фрилансер с несколькими клиентами. Один агент готовит контент-план и креативы по всем проектам сразу, пока вы занимаетесь стратегией. Ключ с суточным потолком гарантирует, что расход предсказуем.

Небольшое агентство. Каждому проекту — свой ключ со своим потолком. Видно, сколько потратил каждый проект, и можно выставить это клиенту без ручного учёта.

Разработчик продукта. Встраиваете генерацию картинок или озвучки в своё приложение: пользователь нажимает кнопку у вас, работу делает платформа, вы платите по факту без подписки.

Владелец интернет-магазина. Автоматическая подготовка карточек: фото товара в интерьере, описание, короткое видео для соцсетей — по расписанию, для новых поступлений.

Тот, кто уже живёт в Claude или ChatGPT. Коннектор превращает привычный чат в рабочее место: просите картинку — получаете картинку, а не совет, каким сервисом её сделать.

Как настроить ИИ-агента: пошагово

1. Откройте раздел «ИИ Агент» в кабинете. Это вкладка «AGI Агент» в верхнем меню. Здесь живёт всё, что касается агентов: подключение к чат-ботам, ключи, аналитика расходов.
2. Решите, какой путь вам нужен. Если хотите работать из чата Claude или ChatGPT — вам нужен блок «Подключение к Claude и ChatGPT» (первый на странице). Если пишете код или у вас свой агент — блок «API ключи для агентов» ниже.
3. Для чата: скопируйте ссылку коннектора. Нажмите «Скопировать URL», затем откройте настройки Claude, найдите раздел коннекторов и добавьте новый, вставив ссылку. Важная деталь: ссылку нужно вставлять именно в настройках, а не в переписку с ботом — из чата подключение не работает.
4. Разрешите доступ. После добавления коннектор попросит войти в Вайб-Маркетолог и подтвердить доступ. Это обычная авторизация: вы разрешаете чат-боту действовать от вашего имени в рамках, которые сами и задаёте.
5. Проверьте, что связь работает. Спросите в чате: «Покажи мой баланс в Вайб-Маркетологе». Если ассистент ответил цифрой — всё настроено. Если сказал, что не может — проверьте, что коннектор появился в списке подключений и включён.
6. Для своего кода: создайте ключ. Нажмите «+ Создать ключ» в блоке «API ключи для агентов». Дайте ключу понятное название — не «ключ 1», а «креативы для проекта Ромашка». Через месяц вы не вспомните, какой из ключей за что отвечает, а название останется.
7. Задайте права под задачу. Это главный шаг с точки зрения безопасности. Ключу выдаются только те права, которые нужны для его работы: чтение данных, создание контента, изменение рекламных кампаний, работа с подключёнными сервисами. Агенту, который рисует картинки, права на рекламные кампании не нужны — не выдавайте их «на всякий случай».
8. Поставьте суточный потолок расходов. Начните с небольшой суммы — 300–500 ₽ в сутки. Потолок работает жёстко: даже если агент сойдёт с ума и отправит сто запросов одновременно, он не потратит больше заданного. Поднять лимит можно в любой момент, когда убедитесь, что агент ведёт себя предсказуемо.
9. Сохраните ключ в надёжном месте. Полностью ключ показывается один раз при создании. Дальше в интерфейсе видно только начало — этого достаточно, чтобы отличать ключи друг от друга, но недостаточно, чтобы им воспользоваться. Храните ключ там, где храните пароли, а не в переписке и не в коде проекта.
10. Сделайте первый запрос — бесплатный. Прежде чем платить за генерацию, попросите оценку: платформа проверит параметры, посчитает цену и покажет остаток суточного лимита, ничего не списывая. Это лучший способ убедиться, что агент формирует запрос правильно.
11. Проверьте журнал. Вернитесь в кабинет — в аналитике агентов должно появиться ваше обращение с датой и кодом ответа. Если запросов не видно, значит агент обращается не туда или не с тем ключом.

Разбор опций и настроек

Права ключа: почему «побольше» — плохая идея

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

Практическое правило: начните с минимума, и если агент упрётся в отказ «недостаточно прав», добавьте именно то право, которого не хватило. В отказе всегда указано, какое именно. Так вы получите набор прав, точно соответствующий задаче, за пару итераций.

Суточный потолок: сколько ставить

Считайте от задачи, а не «на всякий случай побольше». Если агент готовит десять картинок в день по 15–20 ₽, ему хватит 300 ₽ с запасом. Если он делает видео — счёт другой: секунда видео стоит от 10 ₽, и минутный ролик уже уходит за несколько сотен.

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

Повторы запросов: где ломается большинство интеграций

Это самая частая ошибка в агентских интеграциях, и она стоит денег и нервов. Схема ошибки такая: агент отправляет запрос, получает отказ, немедленно повторяет, снова получает отказ — и так тысячи раз, пока кто-нибудь не заметит.

Правильное поведение агента при отказе:

• Отказ из-за самого запроса (неверное поле, нет права, неизвестная модель) — повторять бессмысленно. Нужно исправить запрос. Такие отказы всегда содержат конкретное объяснение: какое поле и что с ним не так.
• Временный отказ (сервис перегружен, внешний поставщик недоступен) — повторять можно, но с нарастающей паузой: 1 секунда, 2, 4, 8. И не больше пяти попыток, после чего остановиться и сообщить человеку.
• Отказ с указанием времени ожидания. Если в ответе есть время, через которое можно повторить — ждите именно столько. Это не рекомендация, а точное значение.

Если агент игнорирует эти правила и продолжает долбить, его ключ получит короткую паузу — с объяснением, что произошло и что делать. Это защита и платформы, и вашего кошелька: пауза прекращает бессмысленный расход.

Идемпотентность: как не заплатить дважды

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

Решение — ключ идемпотентности: любая уникальная строка, которую агент прикладывает к запросу. Если тот же запрос с тем же ключом придёт повторно, платформа вернёт результат первой попытки, а не запустит вторую генерацию. Стоит приучить агента добавлять такой ключ к каждой платной операции — это одна строка в коде, которая экономит деньги в самый неподходящий момент.

Вебхуки вместо опроса: экономия времени и лимитов

Генерация видео занимает минуты. Наивный подход — спрашивать «готово?» каждую секунду. Это расходует лимит частоты запросов и создаёт нагрузку без пользы.

Правильно — подписаться на уведомление: агент указывает адрес, на который платформа сама сообщит о готовности. Тогда агент вообще не опрашивает: он получает готовый результат событием. Если вебхук по каким-то причинам не подходит, опрашивайте не чаще раза в 10–20 секунд.

Ссылки на результат: какую сохранять

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

Оценка стоимости заранее

Бесплатный «сухой прогон» — недооценённая возможность. Он проверяет параметры запроса, считает точную цену и показывает остаток суточного лимита, ничего не тратя. Приучите агента вызывать его перед каждым новым типом операции: так вы поймаете и опечатку в названии модели, и несовместимые параметры, и нехватку денег — до списания, а не после.

Сколько стоит

Доступ к API бесплатный, подписки нет. Платите только за выполненные операции — по тем же ценам, что и в кабинете, с общего рублёвого баланса. Ориентиры:

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

Частые ошибки и как их избежать

• Выдать ключу все права сразу. Ошибка в логике агента превращается из «испорченной картинки» в «изменённую рекламную кампанию». Давайте права по одному, по факту отказов.
• Поставить огромный суточный потолок. Потолок — это не ограничение возможностей, а страховка от собственной ошибки. Начните с малого.
• Повторять запрос без паузы. Самая дорогая ошибка: агент в цикле сжигает лимит частоты, а иногда и деньги. Нарастающая пауза плюс предел попыток — обязательны.
• Не использовать ключ идемпотентности. При обрыве связи агент повторит платную операцию и заплатит дважды.
• Опрашивать статус каждую секунду. Расходует лимит частоты и ничего не ускоряет. Вебхук или опрос раз в 10–20 секунд.
• Хранить ключ в коде проекта. Ключ попадает в историю изменений, а оттуда — куда угодно. Только в защищённом хранилище секретов.
• Прописать названия моделей и цены в коде. Каталог моделей пополняется, цены меняются. Запрашивайте список у платформы.
• Игнорировать текст ошибки. Сообщения конкретные: они говорят, какое поле неверно и что нужно исправить. Агент, который их читает, отлаживается в разы быстрее.

Частые вопросы

Как ограничить расходы ИИ-агента?

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

Что будет, если мой агент сломается и начнёт отправлять запросы без остановки?

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

Нужна ли подписка?

Нет. Доступ к API бесплатный, оплата только за выполненные операции с рублёвого баланса. Неиспользованные деньги остаются на балансе.

Чем коннектор для Claude отличается от прямого обращения к API?

Это два входа к одному и тому же. Коннектор — для работы из чата без кода: подключается в настройках Claude или ChatGPT, вы просто просите словами. Прямое обращение — для своих скриптов и агентов: полный набор методов, вебхуки, собственная логика. Права и суточный потолок настраиваются в кабинете в обоих случаях.

Как понять, что именно делал мой агент?

В разделе «ИИ Агент» есть аналитика: количество запросов, расход, среднее время ответа, активность по дням и по каждому ключу. Каждое обращение записывается с датой, методом и кодом ответа — при спорной ситуации разбор занимает минуты.

Можно ли дать отдельный ключ каждому клиенту или проекту?

Да, и это правильный подход. У каждого ключа свои права, свой суточный потолок и своя статистика расходов. Это удобно и для учёта, и для безопасности: если ключ придётся отозвать, остальные проекты продолжат работать.

Что делать, если агент получает отказ «недостаточно прав»?

В тексте отказа указано, какое право требуется. Добавьте именно его на странице ключа в кабинете. Не выдавайте все права сразу — так вы потеряете смысл ограничения.

Мои данные остаются в России?

Да, платформа работает на российской инфраструктуре в соответствии с 152-ФЗ.

Советы

• Заведите тестовый ключ с потолком 100 ₽. На нём отлаживайте нового агента: ошибки будут стоить копейки, а рабочий ключ останется нетронутым.
• Сначала оценка, потом запуск. Приучите агента вызывать бесплатную оценку стоимости перед каждым новым типом операции — это ловит опечатки и несовместимые параметры до списания.
• Смотрите аналитику раз в неделю. Резкий рост доли ошибок — признак, что агент работает не так, как задумано, даже если результат внешне нормальный.
• Называйте ключи по проектам. Через месяц это единственный способ понять, кто что тратит.
• Не бойтесь начать с коннектора. Даже если в итоге вы будете писать код, подключение к Claude за две минуты покажет, что платформа умеет, и сэкономит время на чтении документации.

Подробнее о том, что изменилось в API и почему — в новости «Безопасность API для ИИ-агентов». Полный справочник методов с примерами — в документации Agent API, а короткая версия для вставки в системный промпт агента — здесь. Если работаете через чат — начните со страницы коннектора.