OpenAI Ads API: автоматизация кампаний, ad groups и отчётности
Что покрывает OpenAI Ads API
OpenAI Ads API - в терминологии OpenAI, Advertiser API, - превращает воркфлоу Ads Manager в программируемые эндпоинты. Она поддерживает CRUD-подобные операции над кампаниями, ad groups, объявлениями, файлами и отчётностью со стандартными JSON-типами, плюс группу conversions для настройки измерения. Запросы уходят на https://api.ads.openai.com/v1, а контекст аккаунта приходит из самого ключа: каждый ресурс, к которому ключ прикасается, принадлежит рекламному аккаунту, ассоциированному с этим ключом. Командам, уже автоматизировавшим Meta или Google, форма покажется достаточно знакомой для планирования, а специфика живёт в нескольких различиях, которые разбирает эта статья.
Ключи: один ключ, один рекламный аккаунт
Выдача ключей живёт в табе Settings в Ads Manager, а не в девелопер-портале. Каждый ключ скоупится на один рекламный аккаунт - зонтичного ключа на все аккаунты нет, - и каждый запрос аутентифицируется bearer-заголовком:
Authorization: Bearer $OPENAI_ADS_API_KEYПартнёрская документация OpenAI хранит ключ в переменной окружения OPENAI_ADS_API_KEY и советует серверный secret manager для него и для любых ключей Conversions API, которые создаёт интеграция. Созвучие имён стоит разрулить сразу: этот ключ принадлежит рекламной платформе и отделён от платформенных ключей OpenAI для моделей - другая система, другой креденшел, другой радиус поражения.
Карта эндпоинтов
Группы эндпоинтов ложатся один к одному на объекты из статьи о стандартных событиях и кампаниях. Campaigns, ad groups и ads поддерживают create, list, retrieve, update и смену состояния под корнем /v1 - кампании живут на /v1/campaigns, - с заголовком Idempotency-Key на созданиях, чтобы ретраи не дублировали объекты. Files загружает удалённые картинки или бинарные ассеты и возвращает file ID, на который ссылается креатив. Insights достаёт агрегированные показатели по скоупам ad account, campaign, ad group и ad, включая сегментные метрики вроде разбивок по продукту, стране и устройству. Bulk API создаёт или обновляет кампании, ad groups и объявления асинхронной джобой - программный эквивалент bulk upload таблицы в UI. Наконец, группа conversions выдаёт пиксели, серверные ключи и настройки событий конверсий для Conversions API, когда эти операции включены аккаунту.
Границы автоматизации: что остаётся в Ads Manager
Три границы держат планы автоматизации честными. Первая: менеджмент product feeds в публичном API отсутствует - создание feed connections, листинг фидов и загрузка каталогов происходят в области Feeds в Ads Manager, а единственная программная точка входа для цен и наличия - Delta Feeds API. Вторая: бюджетное поле кампании в API - lifetime_spend_limit_micros, минимум 1 000 000 micros, тогда как UI Ads Manager предлагает ещё и дневные бюджеты, - расхождение UI/API, которое стоит учитывать, когда тулзы читают бюджеты обратно. Третья: несколько операций - brand updates, менеджмент пикселей, создание ключей conversions, conversion-optimized кампании - должны быть включены аккаунту; 403 или 404 Not found на этих эндпоинтах - сигнал о включении, а не баг вашего запроса.
Partner setup: управление клиентскими аккаунтами
Для агентств и вендоров тулз partner setup у OpenAI описывает рабочий паттерн: настраивать измерение и кампании клиентских аккаунтов ключом, ассоциированным с рекламным аккаунтом каждого клиента, - правило один-ключ-один-аккаунт исключает партнёрский оверрайд. Задокументированные пререквизиты: Ads API-ключ клиентского аккаунта, доступ к сайту и брендовым ассетам клиента и серверный secret manager для ключа Ads API плюс любых ключей Conversions API, созданных при настройке. Когда brand updates возвращают 403, а эндпоинты пикселей и ключей conversions отвечают 404 Not found, разговор о включении принадлежит партнёрскому представителю OpenAI - тот же гейт включения аккаунта из прошлой секции, но глазами агентства.
Минимальный цикл автоматизации
Первому циклу автоматизации не нужно ничего экзотического. Создайте кампанию со status: paused, прикрепите ad groups с их context hints, прикрепите объявления со ссылками на загруженные file ID и оставьте время на валидацию conversion setup, от которого зависят oCPC-кампании. Переводите кампанию в active только после подтверждения измерительной цепочки - механика атрибуции решает, чему научит спенд, - а результаты тяните из insights-эндпоинтов, а не скринскрейпингом UI. MOST гоняет этот цикл для серверной доставки отслеженных конверсий, а бесплатный Pixel Activator валидирует одно событие на лендинг на pixel.way2.us до того, как автоматизация заберёт регулярный поток.