Agent API — VibeMarketolog

Полный справочник API для AI-агентов: генерация контента (видео / изображения / звук / музыка / текст), клонирование голоса, каталог 97 голосов, Яндекс Директ, автопилот. Версия: 2026-06-04. База: https://lk.vibemarketolog.ru/api/agent. Обновления: (1) Grok Video → grok-imagine-video-1-5-preview (image-to-video, grok-itv: 1 image_urls, duration 1–15, без mode). (2) Исправлен выбор голоса в el-tts-turbo — теперь voice_id учитывается (раньше всегда звучал дефолт Rachel).

Содержание

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

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

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

Authorization: Bearer <ваш_api_token>

Получить ключ: страница https://lk.vibemarketolog.ru/#agent → раздел «API-ключи». Ключ виден ОДИН раз при создании — сохраните его сразу. На сервере хранится только SHA-256 хеш.

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

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

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

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

Дневной лимит трат (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://...", "..."],
  "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 означает что деньги уже вернулись на баланс.

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

⚠️ 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 TTV / ITV (xAI)

• TTV (text-to-video, legacy) — grok-ttv-*, до 30 сек, режимы normal/fun/spicy. Если передать image_urls, TTV автоматически апгрейдится до Grok 1.5 Preview (image-to-video, 1–15 сек, без режима).
• ITV (image-to-video) — grok-itv-*, модель grok-imagine-video-1-5-preview: обязательно ровно 1 image_urls, duration 1–15, параметра mode нет, контент-фильтр (nsfw_checker) включён по умолчанию.

# Текст → видео, 10 секунд (legacy TTV)
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",
    "mode": "normal"
  }'

# Картинка → видео (Grok 1.5 Preview, до 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/-30 (text, до 30 сек), grok-itv-10/-20 (image, до 15 сек). Форматы ITV: auto, 1:1, 16:9, 9:16, 4:3, 3:4, 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с).

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"
  }'

# GPT Image 2 / SeeDream / 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 напрямую в видео НЕ передавать — блокируется.

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

Модели:

• el-tts-turbo (29₽) — быстрый TTS, 97 голосов
• el-tts-multilingual-v2 (39₽) — высокое качество, 29 языков, доп. параметры (similarity_boost, style, previous_text, next_text)
• 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.

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 = sha256(your_raw_api_token)
signature = hmac_sha256(request_body, secret)

Пример Python:

import hashlib, hmac

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

Пример Node.js:

const crypto = require('crypto');

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

Важно: проверяйте подпись на 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, баланс не тронут.

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

{
  "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": "sha256(your_raw_api_token)",
  "verify": "hmac_sha256(raw_body, sha256(token)) === 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, 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

Возвращает всё сразу: токен, скоупы, 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 перед записью (бесплатно, ОБЯЗАТЕЛЬНО перед паузой/ставками/бюджетом)

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

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

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

Сотрудник пишет боту в 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.

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:

• Сообщение, забранное но не отвеченное за 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, sha256(raw_token))). Ответьте синхронно за ≤18 сек:

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

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

Лимиты

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

1. Установите приложение «AI-Маркетолог 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. Полные права (write/autopilot) выдавайте только проверенным агентам.

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

Документ обновляется при изменениях API. Последнее обновление: 2026-06-11 (Inbox/Bitrix24-мост: /agent/list, /agent/message, /api/agent/inbox, webhook-url). Связь с поддержкой: @centrmedia.