Снег и Ком
Снег и Ком
Рекламная студия
ДокументацияAPIИнтеграции

Интеграции и API Ads Studio

Этот раздел описывает, как безопасно подключить Ads Studio к вашим системам: выпуск ключей, работа с проектами, запуск генерации, получение статуса и загрузка результата.

Управлять интеграциямиДокументация по студииСоздать первый ролик
Общая модель
В API используются те же сущности, что и в интерфейсе:
  • Project — проект рекламы (формат, длительность, цель, материалы).
  • Job — задача генерации, создаётся на основании проекта (очередь → выполнение → готово/ошибка).
  • Outputs — результаты задачи (например, финальное видео). Ссылки на файлы выдаются как временные подписанные URL.
Важно
Подписанные ссылки на файлы не сохраняются в базе и генерируются заново при каждом чтении задачи. Поэтому для получения актуальной ссылки нужно повторно запросить статус задачи.
Безопасность и доступ
Интеграции работают в контексте командного пространства (company/space). Это означает:
  • Во всех запросах нужен заголовок x-ads-tenant-id — идентификатор пространства.
  • Для API‑ключей используется заголовок x-ads-api-key.
  • Выпуск и отзыв ключей доступны только ролям owner и admin.
Ключи не хранятся в открытом виде
В базе хранится только хэш ключа. Значение ключа показывается один раз при создании — сохраните его в надёжном месте.
Квота и контроль
Для API‑ключей применяется лимит adsApiCallsMonthly. При превышении выдаётся ошибка 429.
Управление ключами (в интерфейсе)
В кабинете компании откройте: Интеграции. Там можно создать и отозвать ключи, а также увидеть их название и «отпечаток» (prefix/last4).
В UI эти запросы идут через прокси Ads UI → Ads API:
  • GET /api/space/keys → Ads API /api/ads/keys
  • POST /api/space/keys → Ads API /api/ads/keys
  • POST /api/space/keys/<id>/revoke → Ads API /api/ads/keys/<id>/revoke
Цикл проекта и генерации
Ниже — рекомендованный порядок действий для интеграций.
Шаг 1
Найти projectId
Интеграции обычно работают с существующими проектами (созданными в UI). Получить список проектов можно через GET /api/ads/projects.
Шаг 2
Запустить генерацию
Создайте задачу через POST /api/ads/generate. Ответ вернёт jobId и статус queued.
Шаг 3
Получить статус и результат
Запрашивайте задачу по GET /api/ads/jobs/&lt;jobId&gt; или список задач проекта GET /api/ads/projects/&lt;projectId&gt;/jobs. В ответе есть outputs с подписанными ссылками.
Примеры запросов (curl)
Во всех примерах замените:
  • TENANT_ID — идентификатор пространства
  • API_KEY — ключ интеграции
1) Список проектов
curl -s   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   https://YOUR_ADS_API_HOST/api/ads/projects
2) Запуск генерации
curl -s   -X POST   -H "content-type: application/json"   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   -d '{
    "projectId": "PROJECT_ID",
    "brief": "Короткий оффер и требования к ролику",
    "durationSec": 12,
    "aspect": "9:16"
  }'   https://YOUR_ADS_API_HOST/api/ads/generate
3) Проверка статуса задачи
curl -s   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   https://YOUR_ADS_API_HOST/api/ads/jobs/JOB_ID
4) Список задач проекта
curl -s   -H "x-ads-tenant-id: TENANT_ID"   -H "x-ads-api-key: API_KEY"   https://YOUR_ADS_API_HOST/api/ads/projects/PROJECT_ID/jobs
Загрузка материалов (UI‑поток)
В интерфейсе загрузка материалов устроена через безопасный presign‑механизм:
  1. Ads UI запрашивает presign: POST /api/uploads/presign
  2. Получает uploadUrl и key
  3. Загружает файл напрямую в хранилище методом PUT uploadUrl
  4. Прикрепляет ключ к проекту: POST /api/projects/&lt;id&gt;/assets
Проверки безопасности
Сервер принимает только ключи вида projects/&lt;projectId&gt;/&lt;kind&gt;/&lt;uuid&gt;.&lt;ext&gt;. Это исключает прикрепление произвольных файлов вне папки проекта.
Интеграции и API Ads Studio