Agent API — VibeMarketolog

Полный справочник API для AI-агентов: генерация контента (видео / изображения / звук / музыка / текст), клонирование голоса, каталог 97 голосов, Яндекс Директ, автопилот. Версия: 2026-07-16. База: https://lk.vibemarketolog.ru/api/agent. Обновления: (0) Озвучка (2026-07-16): el-tts-turbo теперь тарифицируется ПОСИМВОЛЬНО — 6₽ за каждую начатую 1000 знаков (флет 29₽ отменён); одиночный запрос — до 5000 знаков; длинная озвучка: prompt от 5001 до 200 000 знаков автоматически нарезается на куски ~4800, озвучивается и склеивается в один mp3 — /generate вернёт voiceover_id + status_url (GET /voiceover/long/{id}) вместо generation_id. (1) Новые модели: seedance-2-mini (бюджетный Seedance, посекундно, все функции) и nano-banana-2-lite (Gemini 3.1 Flash Lite Image — txt2img + img2img по референсу). (2) Grok Imagine 1.5 — теперь ОБА grok-ttv и grok-itv на движке grok-imagine-video-1-5-preview: duration 1–15 сек, без mode (контент-фильтр включён). (3) «Оживить и Озвучить»: omnihuman-1-5, volcengine-lipsync, omnihuman-1-5/human-identification — посекундная оплата. (4) SeeDream 5 Pro (2026-07-14): seedream-5-pro (text-to-image) и seedream-5-pro-edit (image-to-image, до 10 референсов) — фотореализм до 2K, точный текст на изображении; параметры quality (basic=1K / high=2K) и output_format (png/jpeg). (5) Инструменты директолога (2026-07-14): 7 новых эндпоинтов «Вайб Контекстника» — анализ посадочной, генерация объявлений с нуля, быстрые ссылки/уточнения, прогноз-медиаплан, отчёт для клиента, сливающие фразы/площадки РСЯ, анализ поисковых запросов (см. раздел; каталог с ценами — в GET /capabilities → direct_tools). Полный список моделей и параметров всегда в GET /capabilities.

Содержание

1. Аутентификация
2. MCP: подключение в Claude и ChatGPT (новое: OAuth 2.1-коннектор)
3. Лимиты и скоупы
4. Endpoint reference
5. Генерация: общая модель
6. Видео-модели — параметры и примеры (обновлено: Grok 1.5 Preview image-to-video)
7. Изображения / звук / музыка / текст (обновлено: Suno V5.5, ElevenLabs Multilingual V2, Sound FX, каталог голосов, клонирование)
8. Upload media
9. Webhook callback
10. Pre-charge validation и коды ошибок
11. Яндекс: Метрика, Директ и все скоупы (обновлено: TTL токенов, capabilities, все endpoints)
12. Инструменты директолога (Direct tools) (новое: 7 эндпоинтов Вайб Контекстника)
13. Входящие сообщения (Inbox) — Bitrix24 и другие каналы (новое: мост Bitrix24)
14. FAQ для агентов

Аутентификация

Все запросы требуют Bearer-токен:

Authorization: Bearer <ваш_api_token>

Получить ключ: страница https://lk.vibemarketolog.ru/#agent → раздел «API-ключи». Ключ виден ОДИН раз при создании — сохраните его сразу. На сервере хранится только SHA-256 хеш. Вместе с ключом при создании выдаётся webhook_secret (тоже показывается один раз) — им подписываются вебхуки (см. «Верификация подписи»). Токены, созданные до 2026-07-09, работают на легаси-схеме подписи; чтобы получить выделенный webhook_secret — перевыпустите ключ.

Проверка ключа

curl -s -H "Authorization: Bearer $TOKEN" \
  https://lk.vibemarketolog.ru/api/agent/me

Ответ содержит лимиты, остатки, статус Яндекс OAuth.

MCP: подключение в Claude и ChatGPT

Платформа работает как MCP-сервер (Model Context Protocol): Streamable HTTP, JSON-RPC 2.0, версия протокола 2025-06-18. Её можно подключить к claude.ai, ChatGPT или любому MCP-клиенту и генерировать контент без написания кода.

Два эндпоинта

Ключи oc_... принимаются на обоих эндпоинтах.

9 MCP-тулзов

OAuth 2.1-флоу (для /mcp)

Запрос без токена получает 401 с заголовком WWW-Authenticate, где указана resource-метадата /.well-known/oauth-protected-resource/mcp. Дальше клиент (claude.ai / ChatGPT) выполняет флоу сам:

1. Dynamic Client Registration (RFC 7591) — POST /oauth/register;
2. PKCE S256 — GET /oauth/authorize → consent-экран → POST /oauth/token;
3. Refresh rotation — refresh-токен ротируется при каждом обновлении.

Метадата authorization-сервера: /.well-known/oauth-authorization-server. Скоупы OAuth: read, generate.

Биллинг: списания идут с рублёвого баланса владельца аккаунта; дневной лимит по умолчанию — 500 ₽/день на подключение (меняется в ЛК). Отзыв доступа: ЛК → вкладка «ИИ Агент» → «Подключённые приложения» → «Отозвать».

Подключение в Claude (claude.ai)

1. Откройте claude.ai → Settings → Connectors;
2. Нажмите Add (вверху справа) → Add custom connector;
3. Вставьте URL https://lk.vibemarketolog.ru/mcp;
4. Нажмите Connect;
5. Войдите в Вайб-Маркетолог;
6. Нажмите «Разрешить доступ» на consent-экране;
7. Готово — тулзы доступны в чате.

Доступно на всех тарифах claude.ai (Free — 1 коннектор). В каталоге коннекторов Anthropic нас нет — подключение только по URL.

Подключение в ChatGPT

Settings → Apps & Connectors → Developer mode (тарифы Plus/Pro/Business) → добавить коннектор по URL https://lk.vibemarketolog.ru/mcp, аутентификация — OAuth. Deep Research использует тулзы search/fetch.

Поллинг и результат

Генерация асинхронная: после generate_content опрашивайте get_generation_status каждые 10–15 секунд (image ~30–90 сек, video — до 30 минут). Готовый результат — поле display_url: подписанная ссылка вида https://lk.vibemarketolog.ru/files/generation/{id}?expires=…&signature=…, работает БЕЗ логина 7 дней (при каждом опросе статуса выдаётся свежая; файл навсегда остаётся в галерее ЛК). file_url — та же генерация в ЛК под сессией. result_url/result_urls при наличии локальной копии тоже указывают на подписанные ссылки нашего домена; срок действия ссылок продублирован явным полем expires_at (ISO 8601). URL апстрим-провайдеров в ответах API не отдаются.

Лимиты и скоупы

🔒 Least privilege для Яндекса. Сырой OAuth-токен (со всеми правами, что владелец выдал на экране согласия — вплоть до почты и Диска) отдаётся только под scope yandex. Ключу с одним read доступны безопасные прокси-операции Директа/Метрики/WordStat, но не сам токен. Токены без явного списка scope (полный доступ) получают /yandex как раньше.

Дневной лимит трат (daily_spend_limit) настраивается на странице токена. Когда лимит достигнут — 429 daily_spend_limit_exceeded.

Endpoint reference

Совет: перед интеграцией сделайте GET /capabilities — там лежит полная JSON-схема всех моделей и их параметров.

Генерация: общая модель

POST /generate

Универсальная точка входа: одинаковый формат для всех типов (image/text/video/voice/music).

Базовые поля:

Остальные параметры — модель-специфичные (см. далее).

Ответ

{
  "status": "processing",
  "generation_id": 5811,
  "task_id": "task_xxx",
  "cost": 196,
  "balance_after": 4504.0
}

generation_id сохраните — по нему опрашиваете статус.

GET /generation/{id}/status

{
  "status": "complete",           // pending | processing | complete | error
  "generation_id": 5811,
  "task_id": "task_xxx",
  "model": "grok-itv-10",
  "type": "video",
  "result_url": "https://...",    // временный URL провайдера — ПРОТУХАЕТ
  "result_urls": ["https://...", "..."],
  "display_url": "https://lk.vibemarketolog.ru/files/generation/5811?expires=…&signature=…", // подписанная, без логина, 7 дней
  "file_url": "https://lk.vibemarketolog.ru/newuser/file/5811",    // та же генерация в ЛК (нужен вход)
  "thumbnail": "https://...",
  "title": null,
  "duration": "10s",
  "cost": 196.0,
  "error_message": null,
  "refunded": false,
  "created_at": "2026-05-11T01:50:34+00:00",
  "updated_at": "2026-05-11T01:54:12+00:00"
}

При ошибке error_message содержит человекочитаемую причину; refunded=true означает что деньги уже вернулись на баланс.

Пользователю показывайте display_url — подписанную ссылку, работающую без логина 7 дней (nullable: null, пока файл не сохранён локально; при новом опросе статуса выдаётся свежая). file_url — файл в ЛК под сессией, хранится бессрочно. result_url — временный URL провайдера, протухает; использовать не рекомендуется.

Видео-модели — параметры и примеры

⚠️ image-to-video: правильное поле под модель

Самая частая ошибка агентов — слать image_input для видео. image_input существует только для type: image (nano-banana / gpt-image / seedream). Видео-модели его не читают → вы получите чистый text-to-video, а деньги спишутся. Используйте поле из таблицы:

Не уверены, какое поле принимает модель? Сделайте GET /capabilities (required/optional по каждой модели) или POST /generate/estimate с strict=true — он покажет rejected поля без списания.

Grok Imagine 1.5 — TTV / ITV (xAI)

Единый движок grok-imagine-video-1-5-preview. Обе модели: duration 1–15 сек, resolution 480p/720p, параметра mode нет (контент-фильтр включён по умолчанию). Самый доступный способ сделать видео.

• TTV (text-to-video) — grok-ttv-*, только prompt.
• ITV (image-to-video) — grok-itv-*: обязательно ровно 1 image_urls (оживление вашей картинки).

# Текст → видео, 10 секунд
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "grok-ttv-10",
    "prompt": "cinematic shot of a fox jumping in autumn forest, golden hour",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

# Картинка → видео (image-to-video, до 15 сек)
# Шаг 1 — загружаем картинку
curl -X POST https://lk.vibemarketolog.ru/api/agent/upload-media \
  -H "Authorization: Bearer $TOKEN" -F "file=@hero.png"
# → { "url": "https://lk.vibemarketolog.ru/uploads/agent/123/2026-05-11/.../hero.png" }

# Шаг 2 — запускаем grok-itv-10 с image_urls (ровно 1)
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "grok-itv-10",
    "prompt": "camera slowly zooms into product, light flicker",
    "image_urls": ["https://lk.vibemarketolog.ru/uploads/agent/..."],
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Тиры по длительности: grok-ttv-10/-20, grok-itv-10/-20 (обе до 15 сек; -30 устарел — длительность клампится до 15). Форматы (aspect_ratio): auto, 1:1, 16:9, 9:16, 3:2, 2:3. Расширение / апскейл: grok-extend (ref_task_id, extend_at, extend_times), grok-upscale (ref_task_id).

Veo 3.x (Google)

Кинематографическое качество, до 8 сек, нативный звук, до 1080p.

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "veo3_fast",
    "prompt": "morning fog rolling over a mountain lake, drone shot",
    "aspect_ratio": "16:9",
    "duration": 8,
    "resolution": "720p",
    "generate_audio": true
  }'

# Image-to-video режим:
# Передайте image_urls + generation_type=image-to-video

Seedance 2.0 / Fast (ByteDance)

Cinematic-видео, 4-15 сек, до 9 reference images, до 3 reference videos / audio, first_frame_url и last_frame_url для image-to-video.

# Text-to-video, 9:16 для рилсов, Quality 1080p
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "seedance-2",
    "prompt": "stylish young woman walking through neon-lit Tokyo street at night, slow motion",
    "aspect_ratio": "9:16",
    "duration": 8,
    "resolution": "1080p",
    "generate_audio": true
  }'

# Image-to-video через first_frame_url
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "seedance-2-fast",
    "prompt": "the model starts walking towards the camera, smiles",
    "first_frame_url": "https://lk.vibemarketolog.ru/uploads/agent/...",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "9:16"
  }'

# С референсами (стиль / звук / движение)
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "seedance-2",
    "prompt": "...",
    "reference_image_urls": ["https://.../ref1.png", "https://.../ref2.png"],
    "reference_audio_urls": ["https://.../voice.mp3"],
    "duration": 10
  }'

Ограничения: prompt до 20000 chars, duration 4-15с, max 9 reference images, max 3 reference videos (общая длина ≤15с), max 3 reference audio (общая длина ≤15с).

Seedance 2 Mini (ByteDance)

Бюджетный тир Seedance с посекундной оплатой — самый дешёвый способ получить видео от ByteDance. Те же функции, что у Seedance 2.0 (референсы фото/видео/аудио, AI-звук, веб-поиск, first/last frame), но resolution только 480p/720p (без 1080p). duration 4–15с. Модель: seedance-2-mini.

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "seedance-2-mini",
    "prompt": "first-person kitchen baking vlog, hands only, warm morning light",
    "aspect_ratio": "16:9",
    "duration": 8,
    "resolution": "720p",
    "generate_audio": true
  }'

Форматы: 16:9, 4:3, 1:1, 3:4, 9:16, 21:9. Остальные лимиты — как у Seedance 2.0.

Kling 3.0 Motion Control

Перенос движений с reference-видео на загруженного персонажа (танцы / жесты / мимика). Сохраняет черты лица и идентичность героя из фото.

Биллинг: per-second. Цена = ceil(video_duration) × per_sec ₽, где video_duration ограничен 3–30 секундами.

• motion-control-720p — 15 ₽/сек (мин 45 ₽, макс 450 ₽)
• motion-control-1080p — 22 ₽/сек (мин 66 ₽, макс 660 ₽)

Ограничения:

• Reference video: 3–30 сек, MP4/MOV, ≤50 MB на upload, aspect 2:5–5:2.
• Character image: JPEG/PNG, >300px, aspect 2:5–5:2, чёткий портрет (голова + плечи).
• character_orientation="image" требует видео ≤10 сек. На сервере жёсткая валидация — при >10s вернётся 422.
• character_orientation="video" — до 30 сек (рекомендуется по умолчанию).

# Шаг 1 — загружаем фото персонажа
IMG_URL=$(curl -s -X POST https://lk.vibemarketolog.ru/api/agent/upload-media \
  -H "Authorization: Bearer $TOKEN" -F "file=@character.png" | jq -r .url)

# Шаг 2 — загружаем reference-видео с движением (бэкенд ffprobe вернёт duration)
RESP=$(curl -s -X POST https://lk.vibemarketolog.ru/api/agent/upload-media \
  -H "Authorization: Bearer $TOKEN" -F "file=@dance_reference.mp4")
VID_URL=$(echo "$RESP" | jq -r .url)
DUR=$(echo "$RESP" | jq -r .duration)   # например 13.23

# Шаг 3 — запускаем (по умолчанию orient=video — переносит позу/повороты из видео)
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{
    \"type\": \"video\",
    \"model\": \"motion-control-720p\",
    \"character_image_url\": \"$IMG_URL\",
    \"reference_video_url\": \"$VID_URL\",
    \"character_orientation\": \"video\",
    \"video_duration\": $DUR,
    \"prompt\": \"smooth dance moves, cinematic lighting\"
  }"

Параметры:

Что НЕ передавать: поле background_source (input_video/input_image) — Оператор (Kling 3.0 prod-прокси) его игнорирует, удалено из API ещё в мае 2026.

Kling 3.0 (std / pro)

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "kling-3.0-pro",
    "prompt": "...",
    "aspect_ratio": "16:9",
    "image_urls": ["https://.../start.png"],
    "duration": 5,
    "sound": true
  }'

VEED Avatar

Говорящая голова из текста.

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "veed-avatar",
    "avatar_id": "anna_pro",
    "script": "Привет! Расскажу про новинку нашего магазина.",
    "language": "ru",
    "prompt": "AI avatar speech"
  }'

TopView URL-to-Video

Вставка URL продукта → AI создаёт рекламный ролик.

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "topview-url-video",
    "source_url": "https://example.com/product",
    "video_length": 30,
    "language": "ru",
    "prompt": "promo video"
  }'

Особенность: превью-фаза бесплатна. HD-рендер оплачивается отдельно при подтверждении.

Изображения / звук / музыка / текст

Изображения

# Z-Image (быстрая)
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"image","model":"z-image","prompt":"cyberpunk warrior, neon","aspect_ratio":"1:1"}'

# Nano Banana Pro 2K с правкой существующего изображения
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "nano-banana-pro-2k",
    "prompt": "remove the watermark, brighten",
    "image_input": "https://lk.vibemarketolog.ru/uploads/agent/...",
    "aspect_ratio": "16:9"
  }'

# Nano Banana 2 Lite (Gemini 3.1 Flash Lite) — быстро и дёшево, txt2img + img2img
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "nano-banana-2-lite",
    "prompt": "add a cheerful hat to the character, keep everything else",
    "image_input": "https://lk.vibemarketolog.ru/uploads/agent/...",
    "aspect_ratio": "1:1"
  }'
# ⚠️ Lite поддерживает aspect_ratio только 1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / auto
#    (16:9, 9:16, 21:9 автоматически маппятся на ближайший). image_input до 10 шт.

# SeeDream 5 Pro (ByteDance) — фотореализм до 2K, точный текст на картинке
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "seedream-5-pro",
    "prompt": "рекламный баннер салона красоты, крупный текст «САЛОН КРАСОТЫ»",
    "aspect_ratio": "1:1",
    "quality": "high",
    "output_format": "png"
  }'
# quality: basic=1K (дешевле) / high=2K. output_format: png|jpeg.

# SeeDream 5 Pro Edit — image-to-image по 1–10 референсам
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "seedream-5-pro-edit",
    "prompt": "объедини товар и фон в один премиальный баннер",
    "image_input": ["https://lk.vibemarketolog.ru/uploads/agent/...", "https://lk.vibemarketolog.ru/uploads/agent/..."],
    "quality": "high"
  }'
# image_input: 1–10 стабильных URL (POST /api/agent/upload-media).

# GPT Image 2 / Grok Image — аналогично

Музыка (Suno V5 / V5.5)

Модели: suno-v5 (89₽), suno-v5-instrumental (89₽), suno-v5.5 (99₽, улучшенное качество), suno-v5.5-instrumental (99₽).

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "music",
    "model": "suno-v5.5",
    "prompt": "energetic upbeat pop song about freedom",
    "lyrics": "Verse 1: ...\nChorus: ...",
    "music_style": "pop",
    "style_tags": "upbeat, energetic",
    "vocal_gender": "f",
    "persona_id": "OPTIONAL_CUSTOM_VOICE_ID"
  }'

persona_id — кастомный голос, созданный через POST /voice/validate workflow (см. раздел «Клонирование голоса»).

Gemini Omni — видео + персонаж + голос (Google, движок Veo 3) 🆕

Связанная экосистема: создайте кастомный голос, привяжите его к персонажу, затем подставьте персонажа в видео (character_ids). Голос звучит через персонажа. Русская озвучка по умолчанию.

gemini-omni-video (type: video) — text/image/video-to-video с нативным синхронным звуком. Цена по разрешению: 720p — от 149₽, 1080p — от 299₽, 4K — от 590₽.

⚠️ Фильтр безопасности Google отклоняет (HTTP 400 PUBLIC_ERROR_UNSAFE_GENERATION) сцены риска — люди на высоте, трюки, оружие, реальные знаменитости. Это касается и текста, и загруженных image_urls/video_list/character_ids: если заблокировано с вложением — причина чаще в самом видео/фото, а не в тексте. Средства автоматически возвращаются.

🎙️ Голос в видео — ТОЛЬКО через персонажа. Не передавайте audio_ids напрямую в gemini-omni-video — Оператор отклоняет это content-policy фильтром («flagged ... violating content policies») для любого голоса. Правильно: создайте персонажа с голосом (gemini-omni-character + audio_ids), затем передайте его character_ids в видео — персонаж говорит этим голосом. Без своего голоса модель озвучивает сама на русском (lang:"ru").

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type":"video","model":"gemini-omni-video",
    "prompt":"Кот-маркетолог презентует AI-платформу, неоновая студия",
    "duration":8,"aspect_ratio":"16:9","resolution":"1080p","lang":"ru",
    "character_ids":["CHAR_ID_FROM_OMNI_CHARACTER"]
  }'

gemini-omni-character (type: image, 49₽) — консистентный персонаж из 1 фото + описания. audio_ids (из gemini-omni-audio) привязывает голос к персонажу. Возвращает изображение; result_object.characterId (в GET /generation/{id}/status) → используйте в видео character_ids.

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"image","model":"gemini-omni-character","prompt":"Дружелюбный кот-маскот, фиолетовый неон","image_urls":["https://.../photo.jpg"],"character_name":"ВайбКот","audio_ids":["AUDIO_ID_FROM_OMNI_AUDIO"]}'

gemini-omni-audio (type: voice, 39₽) — кастомный голос-ассет. prompt = название, audio_id = базовый тембр (30 пресетов: achernar, puck, kore, fenrir, sulafat…). НЕ возвращает аудиофайл — только result_object.audioId → передайте его в gemini-omni-character (audio_ids), а персонажа уже в видео (character_ids).

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"voice","model":"gemini-omni-audio","prompt":"Голос бренда","audio_id":"puck","voice_description":"энергичный молодой мужской голос"}'

Рабочий процесс (голос → персонаж → видео): 1) создать голос (gemini-omni-audio) → audioId; 2) создать персонажа (gemini-omni-character + audio_ids:[audioId]) → characterId (персонаж несёт голос); 3) видео (gemini-omni-video) с character_ids:[characterId]. ⚠️ audio_ids напрямую в видео НЕ передавать — блокируется.

Оживить и Озвучить — Omnihuman 1.5 + Lip-Sync 🆕

Два способа: оживить фото (фото говорит/поёт под аудио) и переозвучить видео (пересинхрон губ под новое аудио). Обе модели — посекундная оплата: списывается ceil(длительность) × тариф (минимум 3 сек). Длительность определяется сервером автоматически по загруженным файлам.

omnihuman-1-5 (type: video) — фото + аудио → видео, где субъект (человек/питомец/аниме) говорит/поёт с точным лип-синком. Длина видео = длине аудио. Тариф: 720p — 32₽/сек, 1080p — 42₽/сек.

IMG=$(curl -s -X POST https://lk.vibemarketolog.ru/api/agent/upload-media \
  -H "Authorization: Bearer $TOKEN" -F "file=@portrait.jpg" | jq -r .url)
AUD=$(curl -s -X POST https://lk.vibemarketolog.ru/api/agent/upload-media \
  -H "Authorization: Bearer $TOKEN" -F "file=@voice.mp3" | jq -r .url)
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"type\":\"video\",\"model\":\"omnihuman-1-5\",\"image_url\":\"$IMG\",\"audio_url\":\"$AUD\",\"resolution\":\"1080\",\"prompt\":\"уверенно поёт в микрофон, естественная мимика\"}"

omnihuman-1-5/human-identification (type: video, бесплатно) — служебная детекция субъектов на фото. Возвращает result_object.subject_status (1 — чёткий герой распознан, 0 — лучше взять фото крупным планом). Используйте перед omnihuman-1-5 как проверку пригодности фото; для групповых фото маски подставляются в omnihuman-1-5.mask_url.

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"type\":\"video\",\"model\":\"omnihuman-1-5/human-identification\",\"image_url\":\"$IMG\"}"
# затем GET /generation/{id}/status → result_object.subject_status

volcengine-lipsync (type: video) — готовое видео + новое аудио → пересинхрон губ. Оплата по max(длина видео, длина аудио). Тариф: Lite — 10₽/сек, Basic — 14₽/сек.

VID=$(curl -s -X POST https://lk.vibemarketolog.ru/api/agent/upload-media \
  -H "Authorization: Bearer $TOKEN" -F "file=@clip.mp4" | jq -r .url)
AUD=$(curl -s -X POST https://lk.vibemarketolog.ru/api/agent/upload-media \
  -H "Authorization: Bearer $TOKEN" -F "file=@new_voice.mp3" | jq -r .url)
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d "{\"type\":\"video\",\"model\":\"volcengine-lipsync\",\"video_url\":\"$VID\",\"audio_url\":\"$AUD\",\"lipsync_mode\":\"basic\",\"open_scenedet\":true}"

💡 Посекундная оплата: перед запуском оцените стоимость — длительность × тариф. Например, lip-sync Basic для 3-минутного ролика (180с) ≈ 2520₽. Точная цена возвращается в ответе generate (поле cost).

Голос (ElevenLabs — 4 модели)

Модели:

• el-tts-turbo (посимвольно: 6₽ за каждую начатую 1000 знаков; например 300 знаков = 6₽, 2500 знаков = 18₽) — быстрый TTS, 97 голосов. Одиночный запрос — до 5000 знаков; больше — см. «Длинная озвучка» ниже
• el-tts-multilingual-v2 (39₽) — высокое качество, 29 языков, доп. параметры (similarity_boost, style, previous_text, next_text); лимит 5000 знаков
• el-dialogue-v3 (49₽) — мультиспикер диалог с эмоциональными ремарками
• el-sound-fx-v2 (19₽) — звуковые эффекты из текстового описания

⚠️ ВАЖНО про выбор голоса. Чтобы голос отличался от стандартного, в КАЖДОМ запросе передавайте voice_id. Если его не передать — всегда звучит голос по умолчанию Rachel (женский). Поэтому, если нужен мужской/другой голос, его обязательно надо указать явно.

Как выбрать голос (рабочий процесс):

1. Получите каталог: GET /api/agent/voices (можно с фильтром ?gender=male).
2. Возьмите поле id нужного голоса (это либо имя вроде Roger/Brian, либо ID вроде EkK5I93UQWFDigLMpZcX).
3. Передайте это значение в voice_id при генерации. Принимается и алиас voice — это одно и то же.

TTS (single speaker):

# Сначала подобрать мужской голос:
curl -s -H "Authorization: Bearer $TOKEN" "https://lk.vibemarketolog.ru/api/agent/voices?gender=male" | jq '.voices[].id'

# Затем озвучить им (voice_id = id из каталога):
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "voice",
    "model": "el-tts-turbo",
    "prompt": "Привет, мир! Это тестовая озвучка мужским голосом.",
    "voice_id": "Roger",
    "language_code": "ru"
  }'

voice_id — значение поля id из GET /api/agent/voices: имя голоса (Roger, Brian, Bella) или ID (EkK5I93UQWFDigLMpZcX). Без него используется дефолт Rachel. Алиас: voice.

Длинная озвучка (prompt > 5000 знаков, только el-tts-turbo):

Текст от 5001 до 200 000 знаков не отклоняется, а автоматически обрабатывается как «длинная озвучка»: нарезка на куски ~4800 знаков по границам предложений → последовательная озвучка через очередь (с контекстом соседних кусков для плавной интонации) → склейка в один mp3. Цена та же посимвольная (6₽/1000 от полного текста), списывается при старте, при ошибке возвращается автоматически.

/generate в этом случае возвращает НЕ generation_id, а проект озвучки:

{
  "status": "processing",
  "long_voiceover": true,
  "voiceover_id": 12,
  "chars": 14920,
  "chunks": 4,
  "cost": 90,
  "status_url": "https://lk.vibemarketolog.ru/api/agent/voiceover/long/12",
  "hint": "Poll status_url every 20-30 seconds..."
}

Прогресс и результат — GET /api/agent/voiceover/long/{id} (скоуп read):

curl -s -H "Authorization: Bearer $TOKEN" https://lk.vibemarketolog.ru/api/agent/voiceover/long/12
# processing: {"status":"processing","stage":"processing","chunks_done":2,"chunks_total":4,...}
# готово:     {"status":"complete","generation_id":24001,"display_url":"https://...","duration":812,...}
# ошибка:     {"status":"error","error_message":"...","refunded":true}

Ориентир по времени: ~30–60 секунд на кусок (4 куска ≈ 2–4 минуты). Поллинг каждые 20–30 секунд. idempotency_key поддерживается так же, как в обычном generate. callback_url для длинной озвучки пока не поддерживается — используйте поллинг status_url.

Multilingual TTS (расширенные настройки):

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "voice",
    "model": "el-tts-multilingual-v2",
    "prompt": "Привет! Это качественная озвучка.",
    "voice_id": "Bella",
    "stability": 0.5,
    "similarity_boost": 0.75,
    "style": 0.3,
    "speed": 1.0,
    "previous_text": "Текст перед этим абзацем для плавности",
    "next_text": "Текст после для плавности"
  }'

Диалог (мультиспикер):

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "voice",
    "model": "el-dialogue-v3",
    "prompt": "placeholder",
    "dialogue": [
      {"voice_id": "JBFqnCBsd6RMkjVDRZzb", "text": "Привет! Как дела?"},
      {"voice_id": "Xb7hH8MSUJpSbSDYk0k2", "text": "Отлично! А у тебя?"},
      {"voice_id": "JBFqnCBsd6RMkjVDRZzb", "text": "[whispers] У меня секрет..."}
    ],
    "stability": 0.5,
    "language_code": "ru"
  }'

Популярные пары: George (JBFqnCBsd6RMkjVDRZzb) ♂ + Alice (Xb7hH8MSUJpSbSDYk0k2) ♀, Rachel ♀ + Brian ♂. Stage directions: [whispers], [laughs], [яростно].

Звуковые эффекты:

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "voice",
    "model": "el-sound-fx-v2",
    "prompt": "thunder and heavy rain in a forest",
    "duration_seconds": 8,
    "prompt_influence": 0.7
  }'

Каталог голосов

# Все голоса (97 шт)
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://lk.vibemarketolog.ru/api/agent/voices"

# Фильтры
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://lk.vibemarketolog.ru/api/agent/voices?gender=female&category=professional"

# Только голоса с готовым превью (можно прослушать без генерации)
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://lk.vibemarketolog.ru/api/agent/voices?has_preview=1"

# Поиск
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://lk.vibemarketolog.ru/api/agent/voices?search=calm"

Категории: neutral, character, professional, meditation, announcer.

Превью (бесплатно, без генерации):

• preview_url — готовый EN-сэмпл (характер голоса).
• preview_ru_url — реальный русский сэмпл на el-tts-multilingual-v2 (так голос звучит на русском).
• Фильтр ?has_preview=1 — только голоса с превью.

⚠️ Голоса на русском — ВЕРИФИЦИРОВАНО (замеры F0)

Поле gender размечено по английскому звучанию и на русском часть голосов меняет пол. Мы замерили основную частоту (F0) на русском (el-tts-multilingual-v2) и добавили в /voices поля gender_ru, f0_ru_hz, verified_ru. На русском доверяй именно gender_ru.

Примеры расхождений (EN-метка → реальный русский): Aria female→муж (128 Гц), Charlotte female→муж (145 Гц), River male→жен (175 Гц).

Готовые проверенные списки (поле recommended_ru в ответе /voices):

• 🔵 Гарантированно мужской на ru: Brian, Callum, Will, Charlie, George, Liam, Daniel, Chris.
• 🔴 Гарантированно женский на ru: Jessica, Rachel, Alice, Sarah, Lily, Laura, Matilda.
• ⛔ Избегать на ru (пол расходится/неоднозначен): Aria, Charlotte, River, Eric.

Правила для русского:

• Модель — el-tts-multilingual-v2 (НЕ turbo: на русском занижает тембр).
• Параметры тембра: similarity_boost 0.85, stability 0.5, style 0, speed 1.0.
• Фильтр по верифицированному полу: GET /api/agent/voices?language=ru&gender=female (вернёт только проверенные на ru голоса нужного пола).

# Проверенные мужские голоса на русском:
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://lk.vibemarketolog.ru/api/agent/voices?language=ru&gender=male" | jq '.voices[] | {id, gender_ru, f0_ru_hz, preview_ru_url}'

# Озвучить гарантированно мужским голосом на русском:
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"voice","model":"el-tts-multilingual-v2","prompt":"Текст на русском.","voice_id":"Brian","similarity_boost":0.85,"stability":0.5,"style":0,"language_code":"ru"}'

Клонирование голоса (Suno Voice — 50₽)

Создание кастомного голоса для использования в музыке. Голоса имеют ограниченный срок действия.

Workflow (5 шагов):

1. POST /voice/validate    → task_id     (50₽ — списание)
2. GET  /voice/validate-info?task_id=... → validate_info (фраза для чтения)
3. Записать фразу → загрузить через POST /upload-media
4. POST /voice/generate    → task_id     (бесплатно)
5. GET  /voice/status?task_id=...        → voice_id (бесплатно)
6. Использовать voice_id как persona_id в POST /generate (type=music)

Шаг 1: Загрузка аудио-образца

curl -X POST https://lk.vibemarketolog.ru/api/agent/voice/validate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/my-voice-sample.mp3",
    "vocal_start_s": 0,
    "vocal_end_s": 15,
    "language": "ru"
  }'
# → {"status":"ok","task_id":"abc123","cost":50}

Шаг 2: Получение верификационной фразы (polling)

curl -H "Authorization: Bearer $TOKEN" \
  "https://lk.vibemarketolog.ru/api/agent/voice/validate-info?task_id=abc123"
# → {"validate_info":"Произнесите: ...","task_status":"success"}

Шаг 3-4: Запись и отправка

# Загрузить запись
curl -X POST https://lk.vibemarketolog.ru/api/agent/upload-media \
  -H "Authorization: Bearer $TOKEN" -F "file=@recorded-phrase.mp3"
# → {"url":"https://lk.../uploads/agent/...mp3"}

# Отправить на создание голоса
curl -X POST https://lk.vibemarketolog.ru/api/agent/voice/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"task_id":"abc123","verify_url":"https://lk.../uploads/agent/...mp3"}'

Шаг 5: Получение voice_id

curl -H "Authorization: Bearer $TOKEN" \
  "https://lk.vibemarketolog.ru/api/agent/voice/status?task_id=def456"
# → {"voice_id":"persona_xyz","task_status":"complete"}

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

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"music","model":"suno-v5.5","prompt":"...","persona_id":"persona_xyz"}'

Если голос истёк:

curl -X POST https://lk.vibemarketolog.ru/api/agent/voice/regenerate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"task_id":"abc123"}'
# Затем повторить шаги 2-5

Upload media

POST /upload-media

Загрузка стабильно-доступного файла. URL действует ~7 дней, хранится на нашем домене.

Лимиты:

• Image (jpeg / png / webp / gif): ≤30 MB
• Video (mp4 / mov): ≤50 MB
• Audio (mp3 / wav): ≤15 MB

Запрос (multipart):

curl -X POST https://lk.vibemarketolog.ru/api/agent/upload-media \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/tmp/seed.png"

Ответ (image/audio):

{
  "status": "ok",
  "url": "https://lk.vibemarketolog.ru/uploads/agent/123/2026-05-11/1715387034_a8b2c1.png",
  "kind": "image",
  "mime": "image/png",
  "size": 482103,
  "size_mb": 0.46,
  "expires_at": "2026-05-18T01:50:34+00:00"
}

Ответ (video) — дополнительно содержит duration через ffprobe:

{
  "status": "ok",
  "url": "https://lk.vibemarketolog.ru/uploads/agent/123/2026-05-14/1715387089_b9d2e1.mp4",
  "kind": "video",
  "mime": "video/mp4",
  "size": 5177395,
  "size_mb": 4.94,
  "duration": 13.23,
  "expires_at": "2026-05-21T01:50:34+00:00"
}

Передавай duration в video_duration при POST /generate для motion-control-* — это нужно для per-second биллинга и backend-валидации лимита character_orientation=image (≤10s).

Зачем использовать этот endpoint? Внешние URL (tmpfiles.org, gist, etc.) часто блокируются или истекают раньше чем Оператор успевает скачать файл. Загрузка через /upload-media гарантирует доступность.

Webhook callback

Передайте callback_url в POST /generate — мы пришлём результат сами, как только генерация завершится. Не нужно поллить.

Когда отправляется

• generation.complete — успешно
• generation.error — ошибка (с автоматическим refund при cost_rub > 0)

Доставка

• POST на ваш URL с JSON body
• Retry: 3 попытки, backoff 30s / 120s / 600s
• Timeout: 30 секунд
• Считается успешным любой HTTP 2xx ответ

Headers

Тело

{
  "event": "generation.complete",
  "generation_id": 5811,
  "task_id": "task_xxx",
  "type": "video",
  "model": "grok-itv-10",
  "status": "complete",
  "result_url": "https://...",
  "result_urls": ["https://..."],
  "cost": 196.0,
  "error_message": null,
  "refunded": false,
  "created_at": "2026-05-11T01:50:34+00:00",
  "completed_at": "2026-05-11T01:54:12+00:00",
  "attempt": 1
}

Верификация подписи

Подпись считается так:

secret    = ваш webhook_secret        (выдан один раз при создании ключа)
signature = hmac_sha256(request_body, secret)

Легаси-токены (созданные до 2026-07-09, без выделенного webhook_secret) подписываются по старой схеме secret = sha256(your_raw_api_token). Какая схема у вашего ключа — покажет POST /webhook-test (поле secret_formula). Рекомендуем перевыпустить ключ, чтобы уйти с производного секрета на независимый webhook_secret.

Пример Python (новая схема):

import hmac, hashlib

def verify(body_bytes: bytes, webhook_secret: str, header_signature: str) -> bool:
    expected = hmac.new(webhook_secret.encode(), body_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_signature)

Пример Node.js (новая схема):

const crypto = require('crypto');

function verify(rawBody, webhookSecret, headerSignature) {
  const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(headerSignature));
}

Для легаси-ключа замените webhook_secret на sha256(raw_token) (hex).

Важно: проверяйте подпись на raw bytes тела ДО парсинга JSON.

Pre-charge validation и коды ошибок

Все URL-поля (image_urls, reference_image_urls, reference_video_urls, reference_audio_urls, first_frame_url, last_frame_url, character_image_url, reference_video_url) проверяются HEAD-запросом до списания денег. Если хоть один URL недоступен — HTTP 422, баланс не тронут.

🔒 Все передаваемые нам URL (медиа, callback_url, webhook-URL) должны указывать на публичные хосты. Ссылки на приватные, loopback и зарезервированные адреса (127.0.0.1, localhost, 10.x, 192.168.x, 169.254.x/облачная метадата, ::1 и т.п.) — а также редиректы на такие адреса — блокируются на стороне платформы.

Пример отказа

{
  "error": "media_validation_failed",
  "field": "image_urls",
  "url": "https://tmpfiles.org/dl/...",
  "reason": "unreachable",
  "detail": { "ok": false, "code": "unreachable", "http": 404 },
  "hint": "Use POST /api/agent/upload-media to upload the file and get a stable URL."
}

Коды ошибок

При ошибке status=error через polling/webhook — error_message содержит причину, refunded=true если деньги вернулись.

Strict-mode — защита от лишних списаний

По умолчанию /generate берёт только релевантные поля, а лишние молча отбрасывает. Чтобы поймать ошибку ДО списания, передайте strict=true:

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"video","model":"veo3_fast","prompt":"...","image_input":["https://..."],"strict":true}'

Ответ HTTP 422, деньги не тронуты:

{
  "error": "unknown_or_incompatible_params",
  "model": "veo3_fast",
  "rejected": ["image_input"],
  "hint": "image_input is for type=image only. For image-to-video use: image_urls[] + generation_type=image-to-video (veo3*), ...",
  "valid_params": ["type","model","prompt","callback_url","strict","aspect_ratio","duration","resolution","image_urls","generation_type","generate_audio","negative_prompt","seed"]
}

Без strict запрос выполнится, но в ответе появится поле ignored_params со списком отброшенных полей — используйте его для самодиагностики.

Dry-run — POST /generate/estimate

Те же поля, что у /generate, но без запуска генерации и без списания. Pre-flight перед платной операцией:

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate/estimate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"video","model":"veo3_fast","prompt":"...","first_frame_url":"https://..."}'

{
  "valid": true,
  "dry_run": true,
  "model": "veo3_fast",
  "type": "video",
  "estimated_cost_rub": 120,
  "balance": { "current": 1049, "after": 929 },
  "daily_spend": { "limit": 5000, "today": 340, "within_limit": true },
  "validation": {
    "media": { "first_frame_url": [ { "url": "https://...", "ok": true, "code": null, "http": 200 } ] },
    "required_missing": []
  },
  "rejected": [],
  "valid_params": ["type","model","prompt","..."],
  "warnings": []
}

valid:false — смотрите warnings, rejected, validation.required_missing. Scope: read.

Webhook self-test — POST /webhook-test

Проверьте свой listener и верификацию подписи без реальной генерации:

curl -X POST https://lk.vibemarketolog.ru/api/agent/webhook-test \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"callback_url":"https://your-host/webhook"}'

{
  "delivered": true,
  "http_status": 200,
  "response_time_ms": 142,
  "error": null,
  "signature_sent": "9f86d0...",
  "secret_formula": "your webhook_secret (shown once at token creation)",
  "verify": "hmac_sha256(raw_body, webhook_secret) === X-Vibe-Signature header",
  "headers_sent": ["X-Vibe-Event","X-Vibe-Signature","X-Vibe-Token-Id","X-Vibe-Generation"],
  "payload_sent": { "event": "webhook.test", "...": "..." }
}

Тестовое событие приходит с X-Vibe-Event: webhook.test. Сверьте signature_sent с тем, что вычисляет ваш код по формуле из раздела «Верификация подписи». Scope: read.

Pixel-fidelity при редактировании изображений

Edit-модели (gpt-image-2-edit, nano-banana-pro-*, nano-banana-2-*, seedream-4.5, seedream-5-pro-edit, gpt-image-1.5) делают художественную правку и не сохраняют исходные пиксели байт-в-байт — в GET /capabilities у них стоит preserves_input: false. Для брендинга/логотипов, где нужна точность по гайдлайнам, это учитывайте: модель может слегка перерисовать логотип. Маск-инпейнт (точное сохранение вне маски) пока не поддерживается.

Яндекс: Метрика, Директ и все скоупы

Обновлено 2026-06-11. Multi-tenant OAuth: владелец ключа подключает свои Яндекс-аккаунты на странице /agent/ (verification_code flow, можно несколько аккаунтов). Агент получает доступ ровно к тем сервисам, на которые пользователь выдал права на экране согласия Яндекса.

⚠️ Срок жизни токена — НЕ кешируй надолго

Access-токен Яндекса живёт ~30 минут и автоматически ротируется платформой (cron каждые 2 минуты, окно обновления 20 мин). Правило для агента: перед каждой рабочей сессией с Яндекс-API запрашивай свежий токен через GET /yandex или GET /yandex/token — не храни его дольше пары минут. Поле yd_token_expires в ответе показывает точное время истечения.

Главный endpoint: GET /yandex

Требует scope yandex (или ключ с полным доступом). Ключ, ограниченный только read, получит 403 Insufficient scope — используйте прокси-операции (/campaigns, /wordstat/*, /yandex/counters) либо запросите ключ со scope yandex.

Возвращает всё сразу: токен, скоупы, capabilities, endpoints сервисов, счётчики Метрики.

curl -H "Authorization: Bearer $TOKEN" https://lk.vibemarketolog.ru/api/agent/yandex
# Опционально: ?account=login — выбрать конкретный из привязанных аккаунтов

Ответ (подключено):

{
  "status": "ok",
  "yd_connected": true,
  "token_source": "user_oauth_v2",
  "yd_oauth_token": "y0_AgA...",          // живой access_token (тот же для всех сервисов)
  "metrika_token": "y0_AgA...",
  "yd_login": "client-login",
  "yd_uid": 123456789,
  "yd_token_expires": "2026-06-11T03:43:36+00:00",
  "yd_scopes": ["metrika:read", "metrika:write", "direct:api", "..."],   // до 43 скоупов
  "yd_capabilities": {                     // дерево возможностей по 19 сервисам
    "metrika":  {"read": true, "write": true, "segments": true, "expenses": true, "offline": true, "user_params": true},
    "direct":   {"api": true},
    "wordstat": {"api": true},
    "audience": {"read": true, "write": true},
    "appmetrica": {"read": true, "write": false},
    "webmaster": {"hostinfo": true, "verify": false, "turbopages": false},
    "tracker":  {"read": true, "write": true},
    "disk":     {"read": true, "write": true, "info": true, "app_folder": true},
    "mail":     {"smtp": true, "imap_ro": true, "imap_full": false},
    "calendar": {"all": true},
    "directory": {"read_groups": true, "write_groups": false, "read_domains": true, "write_domains": false},
    "market":   {"partner_api": false},
    "ytm":      {"read": true},
    "partner_office": {"advmarkup": false},
    "mediametrika": {"read": false, "write": false},
    "ad_inventory": {"access": false},
    "distribution": {"all": false},
    "messenger": {"vconf": false},
    "suggest":  {"web_history": false}
  },
  "yd_api_endpoints": {                    // готовые base-URL (null = нет прав)
    "metrika":  "https://api-metrika.yandex.net",
    "direct":   "https://api.direct.yandex.com/json/v5",
    "audience": "https://api-audience.yandex.ru/v1",
    "appmetrica": "https://api.appmetrica.yandex.ru/management/v1",
    "webmaster": "https://api.webmaster.yandex.net/v4",
    "wordstat": "https://api.wordstat.yandex.net",
    "tracker":  "https://api.tracker.yandex.net/v3",
    "disk":     "https://cloud-api.yandex.net/v1/disk",
    "market":   null,
    "calendar": "caldav://caldav.yandex.ru",
    "mail":     {"imap": "imap.yandex.ru:993", "smtp": "smtp.yandex.ru:465", "auth": "xoauth2"}
  },
  "metrika_counters": [{"id": 12345678, "name": "Мой сайт", "site": "example.ru"}]
}

Если не подключено / истекло:

{
  "status": "ok", "yd_connected": false, "yd_status": "expired",
  "reconnect_url": "https://lk.vibemarketolog.ru/#agent",
  "message": "Yandex session expired. Owner must re-connect via /agent/ tab..."
}

→ агент должен сообщить оператору, что нужно нажать «Переподключить» на странице /agent/. token_source: "legacy" (старые подключения) = read-only: только direct:api + metrika:read, без записи.

Вспомогательные Яндекс-endpoints

Как использовать токен напрямую

Один и тот же yd_oauth_token работает во всех Яндекс-API:

# Метрика: визиты за неделю
curl -H "Authorization: OAuth $YD_TOKEN" \
  "https://api-metrika.yandex.net/stat/v1/data?ids=$COUNTER&metrics=ym:s:visits&date1=7daysAgo"

# Директ: список кампаний
curl -H "Authorization: Bearer $YD_TOKEN" -H "Client-Login: $YD_LOGIN" \
  -d '{"method":"get","params":{"SelectionCriteria":{},"FieldNames":["Id","Name","Status"]}}' \
  https://api.direct.yandex.com/json/v5/campaigns

# Почта: SMTP/IMAP через XOAUTH2 с тем же токеном (если выданы scope почты)

Всегда проверяй yd_capabilities перед операцией: если у пользователя нет права (например, metrika.write=false) — Яндекс вернёт 403, не пытайся обойти.

Готовые операции платформы (Директ — без прямых вызовов Яндекса)

• GET /campaigns — список кампаний пользователя на платформе
• GET /campaigns/{id} — детали: группы, объявления, статистика
• POST /campaigns/{id}/sync — выкачать статистику из Директа (5₽)
• POST /campaigns/{id}/analyze — AI-анализ эффективности (29₽)
• POST /campaigns/{id}/optimize — AI-рекомендации по оптимизации (49₽)
• POST /autopilot/run — автопилот: AI делает оптимизации сам (15₽)
• POST /keywords-suggest — WordStat enrichment ключевых слов (33₽)
• POST /safety-check — pre-action risk assessment перед записью (бесплатно, ОБЯЗАТЕЛЬНО перед паузой/ставками/бюджетом)

Инструменты директолога (Direct tools)

Добавлено 2026-07-14. Готовая аналитика и материалы для Яндекс Директа — те же инструменты, что в «Вайб Контекстнике» ЛК. Scope: generate (30 req/min). Оплата с баланса по факту вызова, при любой ошибке — автоматический возврат строго на тот баланс, с которого списали. Живой каталог с актуальными ценами: GET /capabilities → direct_tools.

Два семейства:

• POST /direct/* — работают без кампаний: достаточно URL или списка фраз.
• POST /campaigns/{id}/* — по вашей кампании платформы (нужна синхронизированная статистика: POST /campaigns/{id}/sync). Результат кешируется 24 часа на пару (кампания, период) и в это время отдаётся бесплатно с cached: true; force: true — принудительный свежий платный запуск. Период — days: 1–90, по умолчанию 30.

POST /direct/landing-audit — анализ посадочной (39₽)

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/direct/landing-audit \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://example.ru/landing"}'

Ответ result: score (1–10), summary, strengths[], problems[], recommendations[] ({title, description, priority}).

POST /direct/ads-generate — пакет объявлений с нуля (49₽)

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/direct/ads-generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://example.ru/", "utp": "Доставка за 1 день, гарантия 2 года"}'

url и/или utp — хотя бы одно. По URL сервис сам прочитает оффер сайта. Ответ result.groups[]: combinatorial.titles[], combinatorial.texts[], keywords[]. Отличие от POST /creative-variants: генерирует с нуля без кампании (variants перегенерируют группу существующей).

POST /direct/sitelinks — быстрые ссылки и уточнения (29₽)

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/direct/sitelinks \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://example.ru/"}'

Ответ result: sitelinks[] (8 шт: title ≤30 симв., description ≤60, href_path), callouts[] (6 шт, ≤25 симв.), display_path, tips[]. Лимиты Директа соблюдены — можно вставлять как есть.

POST /direct/forecast — прогноз и медиаплан (49₽)

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/direct/forecast \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"keywords": ["купить диван", "диван угловой"], "target_budget": 50000}'

keywords — до 10 фраз; target_budget (₽/мес) и region_ids[] — опционально. Спрос проверяется по Wordstat. Ответ result: scenarios[] ({name, budget_rub, clicks, leads, cpa_rub}), assumptions[], disclaimer.

POST /campaigns/{id}/report — отчёт для клиента (99₽)

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/campaigns/42/report \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"days": 30}'

Готовый отчёт заказчику языком владельца бизнеса. Ответ result: headline, executive_summary, kpi[] ({name, value, comment}), what_works[], what_to_fix[], next_steps[], client_message (готовое сообщение в мессенджер), _overview, _period, _campaign_name.

POST /campaigns/{id}/waste — сливающие фразы и площадки РСЯ (49₽)

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/campaigns/42/waste \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"days": 30}'

Ответ result: summary, potential_savings_rub, waste_keywords[], waste_placements[], recommendations[], _waste_keywords[] (детально: клики/расход). Если на кампании не настроены цели Метрики, анализ площадок по конверсиям недоступен — придёт _placements_note (значение -- из Reports API не считается нулём конверсий).

POST /campaigns/{id}/search-queries — анализ поисковых запросов (39₽)

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/campaigns/42/search-queries \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"days": 30}'

Разбор реальных запросов показов. Ответ result: summary, negative_keywords[] (в минус), new_keywords[] (в новые ключи), insights[].

Ошибки инструментов

Входящие сообщения (Inbox) — Bitrix24 и другие каналы

Клиенты пишут вашему агенту из внешних каналов (Bitrix24, Telegram, кастомные интеграции) — платформа доставляет сообщения агенту и возвращает ответ в канал.

Тарификация: доставка сообщений и ответы ВАШЕГО агента (inbox/webhook) — бесплатны (входят в тариф). Если агент не забрал сообщение и ответил авто-ответчик платформы (reply_source=platform) — списание с баланса владельца по прайсу текстового чата (как на /text): фактическая модель, Claude Opus 4.8 — 10₽/ответ, страховочный Sonnet 4.6 — 8₽/ответ. При нехватке баланса или превышении дневного лимита ключа авто-ответчик молчит.

Как это устроено

Сотрудник пишет боту в Bitrix24
  → обработчик канала зовёт POST /agent/message (Bearer oc_ ключ клиента)
  → платформа доставляет сообщение АГЕНТУ (inbox-очередь или webhook)
  → агент отвечает → обработчик получает {reply} → клиент видит ответ в чате

Канал ждёт ответ синхронно до 22 секунд. Агент должен отвечать быстро.

Endpoints для КАНАЛА (обработчик Bitrix24 и т.п.)

Эти URL живут без префикса /api (точный формат интеграции Bitrix24), но требуют тот же Authorization: Bearer oc_....

# Список агентов клиента
curl -H "Authorization: Bearer oc_..." https://lk.vibemarketolog.ru/agent/list

# Отправить сообщение и получить ответ
curl -X POST https://lk.vibemarketolog.ru/agent/message \
  -H "Authorization: Bearer oc_..." -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_123",
    "text": "Сколько стоит доставка?",
    "channel": "bitrix",
    "context": {"portal": "b24-xxx.bitrix24.ru", "dialog_id": "chat42", "user_name": "Иван"}
  }'
# → 200 {"reply": "Доставка по Москве — бесплатно от 3000₽", "message_id": 17}

Таймаут (агент не успел за 22 сек):

{"reply": null, "status": "timeout", "message_id": 17,
 "message": "Агент не ответил за 22 сек. Ответ можно забрать позже: GET /agent/message/17"}

HTTP-код всегда 200 — проверяйте поле reply. Поздний ответ агента сохраняется — заберите его GET /agent/message/{id} → {"status":"replied","reply":"..."}.

Идемпотентность: повторный запрос с тем же context.dialog_id + text в окне ~60 сек вернёт уже созданное сообщение (ретраи канала не плодят дубли). Для полного контроля передавайте заголовок X-Idempotency-Key.

Вложения (vision) — Bitrix24 v2

Канал может передать в POST /agent/message массив attachments (до 5; для картинок — прямые/подписанные URL, TTL ~1 час):

"attachments": [
  {"type": "image", "url": "https://b24.vibem.ru/attach/<token>.jpg", "mime": "image/jpeg", "name": "photo.jpg"},
  {"type": "file",  "url": "https://...", "name": "бриф.pdf"}
]

• Вложения доставляются агенту как есть: в GET /api/agent/inbox (поле messages[].attachments) и в webhook-payload agent.message.
• Авто-ответчик платформы понимает медиа: картинки (vision, до 3 файлов ≤4MB; реальный тип определяется по байтам — неверный mime от Bitrix не ломает распознавание), PDF (Claude читает нативно), текстовые файлы (txt/csv/json ≤1MB — содержимое попадает в контекст), голосовые (audio/* ≤4MB — расшифровка через SpeechKit). Прочие типы упоминаются по имени.

CRM-действия (actions) — Bitrix24 v2

Агент может вернуть рядом с reply массив actions — машинные команды Bitrix REST, которые исполняет мост (whitelist crm.* на его стороне):

POST /api/agent/inbox/{id}/reply
{
  "reply": "Создал сделку «Заявка от Ивана» на 50 000 ₽.",
  "actions": [
    {"method": "crm.deal.add", "params": {"fields": {"TITLE": "Заявка от Ивана", "OPPORTUNITY": 50000, "CATEGORY_ID": 0}}}
  ]
}

• До 10 действий, method — строго формат crm.deal.add (lowercase, точки), params — как в Bitrix REST.
• Канал получает их в ответе POST /agent/message → {"reply": "...", "actions": [...], "message_id": N} и в GET /agent/message/{id}.
• Webhook-режим: агент может вернуть actions в синхронном ответе на agent.message.
• Действий нет — просто {reply}, как раньше (обратная совместимость). Авто-ответчик платформы для канала bitrix тоже генерирует actions (тот же whitelist, JSON-ответ модели парсится и фильтруется) — CRM-команды работают даже до включения inbox-цикла реального агента.

Endpoints для АГЕНТА (как получать и отвечать)

Вариант А — polling inbox (просто, рекомендуется):

# Цикл агента: забирай и отвечай
while true; do
  MSGS=$(curl -s -H "Authorization: Bearer oc_..." \
    "https://lk.vibemarketolog.ru/api/agent/inbox?wait=20")
  # для каждого messages[].id — сформируй ответ и отправь:
  curl -s -X POST -H "Authorization: Bearer oc_..." -H "Content-Type: application/json" \
    -d '{"reply":"Ответ клиенту"}' \
    "https://lk.vibemarketolog.ru/api/agent/inbox/$ID/reply"
done

Правила inbox:

• Авто-ответчик: если агент не забрал сообщение за ~4 секунды, платформа отвечает сама от имени агента (Claude, с памятью диалога; reply_source=platform). Клиент в Bitrix всегда получает живой ответ. Агент с работающим inbox-циклом всегда успевает раньше авто-ответчика. Отключить для своего ключа: POST /api/agent/identify {"auto_reply": false}.
• Сообщение, забранное но не отвеченное за 60 сек, выдаётся повторно (re-delivery) — упавший агент не теряет сообщения.
• Повторный reply на отвеченное сообщение → 409 already_replied.
• Ответ после таймаута канала принимается ({"status":"ok","late":true}) — канал заберёт его добором.

Вариант Б — push webhook (быстрее):

# Один раз: включить push-режим
curl -X POST https://lk.vibemarketolog.ru/api/agent/webhook-url \
  -H "Authorization: Bearer oc_..." -H "Content-Type: application/json" \
  -d '{"url": "https://your-host.example/hook"}'

Платформа будет слать POST с событием agent.message (подпись X-Vibe-Signature — та же схема HMAC, что у webhook callback генераций: hash_hmac('sha256', body, webhook_secret); для легаси-ключей — sha256(raw_token)). URL должен быть публичным https:// — приватные/loopback/зарезервированные адреса отклоняются. Ответьте синхронно за ≤18 сек:

200 {"reply": "текст ответа"}

Если webhook недоступен — сообщение автоматически падает в inbox (вариант А продолжает работать как fallback). Отключить: {"url": null}.

Лимиты

Интеграция с Bitrix24 (для пользователей)

1. Установите приложение «AGI Агенты VibeMarketolog» из Bitrix24.Маркет.
2. Создайте API-ключ oc_... на странице /agent/ и вставьте в настройки приложения.
3. Выберите агента из списка.
4. Сотрудники пишут боту в чате Bitrix24 — агент отвечает. История диалогов видна на странице /agent/.

FAQ для агентов

Q: Что если я закрою терминал во время генерации? A: Генерация продолжается на стороне Оператора. При возврате просто GET /generation/{id}/status — результат подтянется. Альтернатива — указать callback_url в /generate, и мы сами пришлём результат пушем.

Q: Как использовать image-to-video для Grok? A: Модель grok-itv-10/-20 (Grok 1.5 Preview) + ровно один image_urls: ["https://..."], duration 1–15. Параметра mode нет. Картинку загрузите через /upload-media.

Q: Можно ли передать ссылку на tmpfiles.org / imgur / pastebin? A: Можно, но НЕ рекомендуется — такие хосты часто блокируются или истекают. Лучше /upload-media — стабильный URL на нашем домене.

Q: Что делать если pre-charge validation сработала ложно (URL рабочий, но мы отказали)? A: Это значит ваш CDN не отдаёт HEAD-запрос или прячет Content-Type. Загрузите файл через /upload-media — это безопаснее.

Q: Webhook не пришёл — что делать? A: Проверьте логи: callback_url должен возвращать 2xx HTTP. Retry: 3 попытки с backoff 30s/120s/600s. После 3-й неудачи мы прекращаем попытки — опросите /generation/{id}/status руками.

Q: Безопасно ли отдавать API-токен агенту? A: Да, если токен с ограниченным scope (generate или read), expiry-датой и желательно IP-whitelist. Учтите: сырой OAuth-токен Яндекса (почта/Диск/календарь) отдаётся только под отдельный scope yandex — не добавляйте его без необходимости. Полные права (write/autopilot/yandex) выдавайте только проверенным агентам.

Q: Где смотреть свежий список моделей? A: GET /api/agent/capabilities — самоописывающийся каталог с параметрами всех моделей.

Документ обновляется при изменениях API. Последнее обновление: 2026-07-09 (безопасность: выделенный webhook_secret для подписи вебхуков + SSRF-фильтр исходящих URL/редиректов). Связь с поддержкой: @centrmedia.