Agent API - Вайб-Маркетолог

Один ключ ко всем нейросетям: видео, изображения, озвучка, музыка, текст — одним POST /generate. Оплата в рублях с баланса личного кабинета. База: https://lk.vibemarketolog.ru/api/agent. Версия документа: 2026-08-13. Живой каталог моделей и цен — GET /capabilities.

Зачем через нас, а не напрямую к провайдерам

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

Первый запрос за 3 минуты

1. Аккаунт — https://lk.vibemarketolog.ru, подтвердите адрес почты (без подтверждения платные вызовы отклоняются).
2. Баланс — пополнение от 100 ₽ в кабинете. Юрлицам доступен счёт и закрывающие документы.
3. Ключ — страница https://lk.vibemarketolog.ru/agent (нужен вход в кабинет) → секция «API-ключи для моего агента» → кнопка «+ Создать ключ» → имя подключения, права (read и generate отмечены по умолчанию) и суточный лимит расходов (по умолчанию 500 ₽). Ключ oc_… и webhook_secret показываются один раз — скопируйте сразу. Там же ключ отзывается в один клик и меняется его лимит.
4. Проверка ключа (бесплатно) — покажет права, лимиты и остаток:

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

5. Смета (бесплатно, ничего не списывает) — то же тело, что у /generate:

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/generate/estimate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"image","model":"z-image","prompt":"логотип кофейни на белом фоне","strict":true}'

6. Генерация — тот же запрос на /generate: вернётся generation_id, дальше опрашивайте GET /generation/{id}/status до stage: "complete" и берите display_url.

Полный список моделей и их параметров всегда в GET /capabilities — на него и опирайтесь в коде, а не на этот документ.

Условия, лимиты и документы

• Правила и оферта: https://lk.vibemarketolog.ru/terms. Обработка персональных данных: https://lk.vibemarketolog.ru/privacy-policy.
• Деньги: списание — в момент запуска генерации, по прайсу модели; смета и валидация бесплатны всегда; при сбое провайдера сумма возвращается на баланс автоматически. Дневной лимит трат ключа задаёте вы сами.
• Ваши данные: промпты и результаты хранятся в вашем аккаунте. Готовый файл доступен по подписанной ссылке или под вашей сессией; ссылки поставщиков в ответах API не отдаются.
• Журнал обращений: каждый вызов, включая неудачную авторизацию, фиксируется с request_id — по нему поддержка разбирает спорный запрос.
• Состояние платформы: GET /health. У открытого тарифа формального SLA с компенсацией нет; договорной SLA, выделенные лимиты и приоритетная поддержка — по партнёрскому соглашению (заявка: https://vibemarketolog.ru/api#lead).
• Поддержка: @centrmedia.

Содержание

• Аутентификация
• MCP: подключение в Claude и ChatGPT
• Навыки для подключённых агентов
• Лимиты и скоупы
• Endpoint reference
• Расходы: куда ушёл каждый рубль — /usage
• Живой голос — wss /live/sessions (gpt-live-1)
• Генерация: общая модель
• Каталог моделей и цен
• Видео-модели — параметры и примеры
• Текстовые модели (type=text)
• Изображения / звук / музыка
• Upload media
• Webhook callback
• Pre-charge validation и коды ошибок
• Входящие сообщения (Inbox) — Bitrix24 и другие каналы
• Brand Voice — профиль бренда для генераций
• FAQ для агентов
• Журнал обновлений

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

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

Authorization: Bearer <ваш_api_token>

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

Если секрет не сохранён или ключ выпущен раньше — перевыпустите секрет, не трогая ключ: в разделе «API-ключи» у нужного ключа нажмите кнопку с круговой стрелкой («Перевыпустить секрет подписи вебхуков»). Новый секрет показывается один раз; прежний перестаёт действовать сразу, а сам API-ключ и все интеграции продолжают работать. Тем же способом переводятся на выделенный секрет ключи, созданные до 2026-07-09 (они работают на легаси-схеме подписи).

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

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

Ответ содержит права ключа (scopes), лимиты, остатки, статус Яндекс OAuth. Перед платными вызовами используйте бесплатную смету POST /generate/estimate (цена и valid без списания), а куда ушли деньги — GET /usage и GET /usage/operations (раздел «Расходы»).

Срок действия ключа

Новый ключ действует 90 дней (expires_at в /me). Ключ, которым пользуются, продлевается сам (с 09.10.2026): если за последние 30 дней по нему был хотя бы один вызов, при подходе к сроку он получает ещё 90 дней — перевыпускать не нужно. Ключ без вызовов за 30 дней получает разовую отсрочку на 7 дней и уведомление, затем перестаёт работать — выпустите новый в кабинете: «ИИ Агент» → «API ключи». Отозванный ключ не продлевается.

Права ключа (scopes)

Права выбираются галочками при создании ключа в кабинете (раздел «API-ключи» → «Создать ключ»). Уже созданному ключу права не добавляются — нужен новый ключ.

Ключ для ИИ-агента — заготовка в окне создания ключа: read + generate + llm:proxy + live + chatbot. Этого хватает на все методы, которые зовёт агент: /api/agent/* (смета, баланс, генерации, каталог голосов), /openai/*, /anthropic/*, /tts, /live/*, /chatbots. Яндекс (yandex, write) и партнёрский direct — отдельно.

Права существующего ключа меняются без перевыпуска: в списке ключей строка «Права» → «Изменить». Секрет на машине агента остаётся прежним, новые права действуют со следующего запроса. Права, выданные владельцем адресно (direct и служебные), при этом сохраняются.

⚠️ Проверка прав fail-closed: пустой список = НЕТ прав. Если эндпоинт отвечает 403 insufficient_scope — в теле придёт required (какое право нужно) и granted (какие есть). Право yandex до 07-09-26 выбрать было негде, и все ключи получали только read+generate — если ваш ключ старше этой даты и /yandex/* отвечает 403, создайте новый ключ с галочкой «Метрика и Директ».

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

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

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

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

Инструменты MCP (76 для подключения ChatGPT/Claude, версия сервера 1.4.0)

Состав tools/list зависит от прав ключа. С 29-09-26 запись в Яндекс Директ открыта всем подключениям с правом generate и платная: direct_import_campaign — подготовить черновик из своей структуры (группы, ключи, объявления со своими ссылками, минус-слова, быстрые ссылки, регион, бюджет; в Директ ещё не уходит) — бесплатно; direct_publish_campaign — отправить в Директ черновиком (показы запускает человек отправкой на модерацию) — 99 ₽; у черновика запуск и неподтверждённый бюджет отказывают без платы, второй заголовок Директ сейчас не сохраняет; direct_resume_campaign, direct_resume_ads, direct_set_budget, direct_set_bids, direct_add_keywords, direct_add_negatives, direct_update_ad, direct_optimize_apply — 9 ₽ за действие (у последнего плюс 15 ₽ работы ИИ); direct_pause_campaign, direct_pause_ads — бесплатно. Цены — настройки mcp_fee_direct_publish, mcp_fee_direct_edit. REST /direct/* по-прежнему по партнёрскому праву direct. Данные Метрики, Директа и сайтов берутся из подключений пользователя в кабинете (/agi → «Подключения»); если Яндекс не подключён, инструмент так и скажет. Цена каждого платного инструмента написана в начале его description — модель обязана назвать её пользователю до вызова.

Генерация и кабинет (10)

Каталог Vibe Landing Kit (3, бесплатно, без авторизации) — стиль и анимации для лендинга

REST-двойники (открыто): GET /design-systems (?q=бриф — подбор), GET /design-systems/{slug} (?format=css|md), GET /motion, GET /motion/{slug}. Исходники каталога и плагин Claude Code — репозиторий vibemarketologru/vibe-landing-kit.

Семантика и Вордстат (5) — те же деньги и лимиты, что у REST-двойников

Начало лендинга (3, бесплатно) — для клиентов без файлов и без MCP prompts (ChatGPT, Claude.ai)

REST-двойники (с 25-09-26, те же лимиты, поля и отказы; счётчики общие с MCP): upload_file → POST /uploads/image, upload_link → POST /uploads/links и GET /uploads/links/{code}, media_check → POST /media/check, video_loop → POST /media/loop, landing_guide → GET /skills/{slug} (landing-ab, landing-media…), brand_profile → GET /brands. Таблица — в разделе «Гипотеза под ключ».

Черновик и превью (с 24-09-26). landing_check сохраняет черновик (draft_id, version, 7 дней) — дальше присылай только patches [{variant a|b|both, find, replace, all?}] (find — точный кусок текущего HTML, ровно одно вхождение; ошибка — черновик не меняется) и b_patches (Б = A + правки); landing_launch / landing_update принимают draft_id вместо HTML. Ответ landing_check содержит preview — снимки первого экрана A и Б на компьютере (1280×800) и телефоне (390×844) с настоящими кадрами и шрифтами, WebP, хранятся 3 дня; preview: false — без снимков. Паспорт дополнительно предупреждает: невидимый fixed-слой у края (iOS 26), loading=lazy у главной картинки, картинки без размеров, анимации в режиме «меньше движения».

landing_launch с dry_run и baseline_cr / target_cr / cpc_rub возвращает sample — сколько визитов на вариант и денег на трафик нужно для вывода, и честно говорит, если цена больше суточного лимита подключения (по умолчанию лимит 2 500 ₽ с 29-09-26, меняется на https://lk.vibemarketolog.ru/agent — кнопка «Изменить лимит» у подключения; #792). landing_status отдаёт test_lead — дошла ли проверочная заявка до владельца; ?v=a / ?v=b — предпросмотр (и для headless-браузера): открывают вариант, но в статистику не идут; для рекламных связок «объявление A → страница A» — ?ad=a / ?ad=b, они считаются отдельно (ab.bundle). Заранее отмеченная галочка согласия блокирует запуск.

get_design_system с format: "css" отдаёт готовые @font-face шрифтов стиля с нашего адреса — страница из веб-чата получает фирменный шрифт без файлов и без CDN (#791).

Гипотеза под ключ (5) — свой HTML лендинга на /w/{slug} с заявками и A/B-тестом (с 24-09-26)

Чат-боты с ИИ (6) — консультант для сайта или лендинга (с 24-09-26)

Пробным ключам чат-боты закрыты (общий аккаунт). Виджет работает и на лендингах /w/* (песочница — #783). Контакт, оставленный посетителем в чате, уходит владельцу уведомлением в кабинет и Telegram (#785).

Двенадцать навыков Vibe Landing Kit 1.2.0 отдаются через prompts/list: landing-ab (маршрут), hypothesis-lab, landing-brief, landing-media, landing-mobile, landing-law-ru, landing-chatbot, ad-match, brand-to-system, а также gpt-image-25, wow-ad-creative, cyrillic-slides. ChatGPT и Claude.ai получают тот же маршрут, что плагин Claude Code; соседние файлы навыка (snippets.md, templates.md) приходят в prompts/get приложениями в конце текста (#788).

Метрика, Директ, сайты (18) — исполняет тот же движок, что веб-агент /agi

Запись в рекламный кабинет (12, только партнёрские ключи с правом direct): direct_create_campaign, direct_publish_campaign, direct_pause_campaign, direct_resume_campaign, direct_set_budget, direct_add_negatives, direct_add_keywords, direct_set_bids, direct_update_ad, direct_pause_ads, direct_resume_ads, direct_optimize_apply. Через OAuth-подключение ChatGPT/Claude недоступны.

Деньги. Смета и плата резервируются в дневном лимите ПОДКЛЮЧЕНИЯ до вызова, после вызова разница с фактом освобождается; отказ инструмента возвращает плату по исходной операции.

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

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

1. Dynamic Client Registration (RFC 7591) — POST /oauth/register. Адреса возврата: https://… и, для локальных клиентов (Claude Code), http://localhost:<порт>/… / http://127.0.0.1:<порт>/… по RFC 8252;
2. PKCE S256 обязателен — GET /oauth/authorize → consent-экран → POST /oauth/token (без code_verifier — 400 invalid_request, с чужим — 400 invalid_grant);
3. Refresh rotation — refresh-токен ротируется при каждом обновлении.

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

Биллинг и лимит: списания идут с рублёвого баланса владельца аккаунта; дневной лимит по умолчанию — 500 ₽ на подключение. Изменить: https://lk.vibemarketolog.ru/agent → «Подключить к Claude и ChatGPT» → «Подключённые приложения» → «Изменить лимит». Отзыв доступа: там же → «Отозвать».

Пошаговые видео-инструкции для ChatGPT, Claude, Claude Code и Cursor — https://lk.vibemarketolog.ru/connect.

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

1. Профиль внизу слева → Settings → Connectors;
2. Add → Add custom connector, название любое, адрес https://lk.vibemarketolog.ru/mcp → Continue;
3. Войдите в Вайб-Маркетолог и нажмите «Разрешить доступ»;
4. В чате: «+» → Connectors → включите переключатель коннектора.

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

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

Нужен тариф Plus, Pro или Business и компьютер. Аватар → Настройки → Безопасность и вход → включить Режим разработчика → Плагины → «+» → Создать MCP-приложение → название «Вайб-Маркетолог», адрес https://lk.vibemarketolog.ru/mcp, аутентификация OAuth → «Создать» → войти и «Разрешить доступ». В чате: «+» → Вайб-Маркетолог. ChatGPT запоминает список инструментов при подключении: после обновления сервера обновите приложение в настройках или подключите заново.

Подключение в Claude Code

claude mcp add --transport http vibemarketolog https://lk.vibemarketolog.ru/mcp

Затем в Claude Code: /mcp → vibemarketolog → Authenticate — откроется браузер со входом и «Разрешить доступ». Без браузера (сервер, CI) — ключом: --header "Authorization: Bearer oc_…".

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

Генерация асинхронная: после 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 не отдаются.

Навыки для подключённых агентов

Навык — это готовая инструкция «как правильно сделать вот такую работу нашими моделями»: структура промпта, режимы, цены, проверенные приёмы и типичные провалы. Мы держим их на сервере, а не в этой публичной странице, по двум причинам: инструкция обновляется вместе с прайсом и моделями (и не может от них отстать), а доступ к ней получает тот, кто реально подключён.

Навыки доступны только по подключению. Ни один из способов не отдаёт тело навыка анонимно.

Способ 1: Claude Code и claude.ai — через MCP

Подключите наш коннектор (см. раздел «MCP: подключение в Claude и ChatGPT») — и навыки появятся у клиента как готовые промпты. Протокольно это prompts/list и prompts/get; оба требуют авторизации (OAuth-подключение или API-ключ, scope read). Без токена сервер отвечает -32001 Missing token.

curl -s -X POST https://lk.vibemarketolog.ru/api/mcp \
  -H "Authorization: Bearer $VM_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"prompts/list"}'

Способ 2: любой агент — через Agent API

GET /api/agent/skills            # список: slug, заголовок, описание, теги
GET /api/agent/skills/{slug}     # тело навыка целиком (поле body, markdown)

Scope read. Список дешёвый — его можно звать при старте сессии; тело подтягивайте под конкретную задачу.

Что сейчас в библиотеке

Актуальный список всегда возвращает GET /api/agent/skills — таблица выше может отставать на один релиз, API не отстаёт никогда.

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

🔒 Права выдаются явно (fail-closed). Каждый метод API привязан к своему праву, и ключ получает доступ только к тем методам, права на которые ему выданы. Ключ без прав не может ничего: пустой список больше не означает полный доступ. Новый ключ по умолчанию создаётся с read и generate; остальные права владелец аккаунта выдаёт осознанно на странице ключа. Если метод потребовал права, которого нет, приходит 403 insufficient_scope с полями required (какое право нужно) и granted (какие есть).

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

Дневной лимит трат (daily_spend_limit) настраивается на странице токена. Когда лимит достигнут — 429 daily_spend_limit_exceeded. Лимит занимается атомарно, поэтому параллельные запросы его не обходят.

Ограничение по IP (allowed_ips) действует на всех каналах доступа сразу: REST, MCP и проверка ключа.

Все обращения к API — включая неудачные попытки авторизации — фиксируются в журнале с отметкой времени; владелец аккаунта видит их в кабинете, поддержка — по request_id из ответа об ошибке.

Endpoint reference

Модели чат-ботов (с 06-10-26). Единый список — GET /modules → chatbots.models[]: slug (постоянный: новая версия модели получает новый слаг, старый остаётся псевдонимом с преемником), title (линейка «Вайб …»), model_name и vendor (настоящая модель и поставщик), display_name («Вайб Лайт · GPT-6» — так показываем людям), hint, price_rub за ответ, tier, vision, search, recommended, available + reason_human. Сейчас: gpt-5-nano Вайб Мини · GPT-5 nano 2 ₽ · gpt-4o-mini Вайб Старт · GPT-4o mini 2 ₽ · deepseek-v4-1-flash Вайб Экспресс · DeepSeek V4.1 Flash 2 ₽ · gpt-6-luna Вайб Лайт · GPT-6 3 ₽ (рекомендуем, по умолчанию) · gemini-3-8-flash Вайб Турбо · Gemini 3.8 Flash 5 ₽ (поиск Google) · gpt-6-1-sol Вайб Мастер · GPT-6.1 Sol 12 ₽ · claude-sonnet-5-5 Вайб Профи · Claude Sonnet 5.5 15 ₽. Сняты с выбора: gpt-5, gpt-4o, gpt-5-mini, claude-haiku-4-5 → Вайб Лайт; gpt-5.5 → Вайб Мастер; claude-sonnet-4-5-20250929, claude-opus-4-8 → Вайб Профи; gemini-3-6-flash, gemini-3-pro-preview → Вайб Турбо — боты на них отвечают преемником по его цене. Если поставщик модели отказал, бот отвечает резервной моделью по той же цене (reason_human об этом говорит); если не ответил и резерв — деньги за ответ возвращаются автоматически. В /modules → chatbots.advice[] — советы сменить модель по всем ботам аккаунта (только с доказанной причиной; пусто — советов нет).

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

Семантика для сайта — POST /semantics

Ключевые запросы из Яндекс Вордстата для рекламного лендинга, разложенные по блокам страницы. Первый шаг перед текстами лендинга и объявлений. Право generate, MCP-двойник — build_semantics.

POST /api/agent/semantics
{
  "topic": "кухни на заказ в Казани",
  "seeds": ["кухни на заказ"],          // до 3 главных фраз, 2–4 слова без города (иначе берутся из topic)
  "depth": "quick",                     // quick — 49 ₽, до 100 ключей; deep — 149 ₽, до 500 ключей + сезонность + заголовки А/Б
  "region_ids": [43],                   // регионы Яндекса: 213 Москва, 2 СПб, 43 Казань; пусто — вся Россия
  "negative_words": ["бу", "авито"],
  "ab_headlines": false,                // заголовки А/Б и для quick
  "dry_run": false,                     // true — смета без списания
  "idempotency_key": "…"                // повтор с тем же ключом отдаёт прошлый ответ без списания
}

Ответ 200: keywords[] {phrase, freq, intent, cluster}, clusters[] {name, block: hero|benefits|pricing|how|faq|proof|lead_form|not_for_landing, intent, head, freq_sum, phrases[], headline_a?, headline_b?}, negative_suggestions[], seasonality[] {month, freq} (deep), live_calls, cached_calls, cost, balance_after. Частотность — показы в месяц по Вордстату; её никогда не придумывает модель, модель только раскладывает фразы по группам.

Деньги. Цена фиксированная за уровень; одинаковые запросы в течение 7 дней берутся из кеша. Вордстат не ответил — 503 wordstat_unavailable и полный возврат; по теме нет ни одной фразы — 422 no_phrases и полный возврат. Не хватает средств — 402 со ссылкой на пополнение; бонусы до подтверждения почты — 402 email_confirmation_required. Не больше 20 сборов в час на аккаунт (429 rate_limited): у Вордстата общая квота проекта.

Гипотеза под ключ — /landings

Агент собирает лендинг сам (Claude Code, Cursor, ChatGPT), а у нас одной командой получает то, чего у него нет: адрес, приём заявок, A/B-тест с честной статистикой и паспорт качества. Цены по решению владельца (24-09-26): запуск 990 ₽, «Про-версия победителя» 4 500 ₽; паспорт, правки и итоги — бесплатно. Настройки agent_landing_launch_price, agent_landing_pro_price. Право generate (чтение итогов — read). Пробные ключи самостоятельной регистрации лендинги не запускают (общий аккаунт — 403 sandbox_not_allowed).

Файлы и медиа для лендинга (REST-двойники MCP, с 25-09-26). Бесплатно; лимиты и счётчики общие с MCP-инструментами, пробным ключам — 403 sandbox_not_allowed.

Медиа и файлы. Свои генерации вставляйте как vm-gen:ID в любом атрибуте (src, srcset, poster) — при запуске номер станет постоянной ссылкой (только свои готовые генерации; чужой номер останется как есть с заметкой в notes). Подписанные display_url и адреса /newuser/file/{id} тоже распознаются. Шрифты, петли видео и аудиофайлы — в assets: [{path, content_base64}]: woff2, woff, png, jpg, webp, gif, ico, mp4, webm, mp3, m4a, ogg, wav; до 6 МБ файл, до 25 МБ вместе, до 40 файлов; тип проверяется по содержимому. SVG не принимаем файлом (открытый напрямую, он исполнял бы скрипты на нашем домене) — встраивайте в разметку. Ссылки в HTML — тем же относительным путём, что path.

Что страница получает. Отдаётся под CSP sandbox плюс строгие правила: скрипты — встроенные и Метрика, сетевые запросы и отправка форм — только к нам и в Метрику, base-uri 'none'. Наш Tailwind и набор анимаций конструктора к импортированной странице НЕ добавляются. Добавляются приёмник заявок (перехватывает любую форму с полями), счётчик Метрики владельца (если указан) и маленькая подпись.

Паспорт. Блокируют запуск: поле пароля или банковской карты, нет meta viewport, нет формы с телефоном или почтой, нет галочки согласия 152-ФЗ, скрипты/стили/шрифты с чужих серверов, нераскрытые ссылки vm-gen:ID (генерация чужая или не готова), горизонтальный скролл на 360/390 px, нет кнопки на первом экране 390×844, браузер не ответил дважды (без него не проверены телефон и первый экран; деньги не списываются). Мобильные предупреждения (с 24-09-26): запрет масштаба в viewport, поля ввода мельче 16 px (iPhone увеличивает страницу), кнопки и ссылки вне текста меньше 44×44, прозрачный фон html/body (Safari iOS 26 красит панели по фону корня), видео с autoplay без muted/playsinline, скролл на 320 px и на телефоне боком (844×390), нет кнопки на первом экране повёрнутого телефона. Проверка идёт в Chrome в две волны окон, не больше трёх паспортов на сервер одновременно. Предупреждения: lang, title, H1, политика, медиа первого экрана, чужие адреса картинок, reduced-motion, мелкий текст, нечитаемые места (их цвет поправляется при запуске автоматически отдельным блоком стилей). Текст поверх картинки, видео или градиента по цвету предков не оценивается. Разметка (с 24-09-26, как у офлайн-паспорта tools/passport.mjs): заранее отмеченная галочка согласия, поле телефона с type="number" или без autocomplete="tel", ссылки t.me вместо telegram.me, @font-face без font-display — предупреждения.

Деньги и надёжность. Одно списание на запуск, журнал landing_launches с уникальным ключом: повтор с тем же idempotency_key (или тем же HTML) отдаёт прошлый результат с replayed: true. Сбой после списания — возврат по исходной операции, сайт и файлы убираются, статус refunded. Проверочная заявка идёт через настоящий приёмник POST /w/{slug}/lead и не попадает в статистику A/B.

Чат-боты: Telegram и виджет для сайта

С 10-09-26 агент может делать с ботом клиента всё то же, что человек в кабинете: создать, настроить, научить, посмотреть переписку с клиентами.

С 20-09-26 бот стал продавцом, а не только консультантом. Четыре вещи, которых не было:

• видит фотографии. Покупатель присылает снимок в виджет или в Telegram, бот отвечает по содержанию. Распознавание моделью — 3 ₽ надбавкой к ответу;
• знает каталог. Фид магазина или таблица становятся знаниями бота вместе с ценой, артикулом и наличием. 0,3 ₽ за позицию, смета до загрузки, обновление по расписанию;
• узнаёт товар по фото БЕСПЛАТНО. Если каталог подготовлен (0,2 ₽ за картинку разово), снимок покупателя сравнивается с отпечатками картинок каталога: ответ мгновенный, модель не вызывается, надбавка не берётся. Узнаются пересжатые кадры и обрезки из сторис;
• соблюдает правила владельца. Жёсткое правило останавливает ответ и передаёт разговор человеку, стилевое считается. Правило в инструкции модели исполняется через раз, проверка в коде — всегда.

⚠️ Порядок при фотографии важен для цены: сначала бесплатный поиск по каталогу, и только если каталог кадр не узнал — платное распознавание моделью. Поэтому подготовленный каталог экономит владельцу деньги на каждом фото.

Два вида ботов, разный путь создания:

Создать бота в Telegram

curl -X POST https://lk.vibemarketolog.ru/api/agent/chatbots \
  -H "Authorization: Bearer $VIBE_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Кофейня Вайб"}'

{
  "status": "ok",
  "create_url": "https://t.me/newbot/vibemarketolog_bot/kofeinia_vaib_x7q2bot?name=Кофейня%20Вайб",
  "next": "Покажите ссылку человеку. Он подтвердит имя в окне Telegram — бот создастся и появится в его кабинете сам…"
}

Токен бота приходит нам от Telegram: клиент его не видит и никуда не копирует. Ходить в @BotFather не нужно. После подтверждения бот появляется в GET /chatbots.

⚠️ Кабинет клиента должен быть связан с Telegram (карточка «Telegram» в «Подключениях»), иначе мы не поймём, чей это бот, — метод скажет об этом прямым текстом.

Создать виджет для сайта

curl -X POST https://lk.vibemarketolog.ru/api/agent/chatbots/site \
  -H "Authorization: Bearer $VIBE_KEY" -H "Content-Type: application/json" \
  -d '{"title": "Консультант кофейни", "instructions": "Отвечай кратко и по делу…", "model": "gpt-5-mini"}'

В ответе — chatbot_id, uuid и готовый embed_code: строка <script> для вставки на сайт.

Научить бота

Порядок ровно такой, и второй шаг обязателен:

# 1. знание (5 ₽): текст или пара «вопрос — ответ»
curl -X POST .../chatbots/105/knowledge -d '{"question":"Сколько стоит доставка?","content":"По городу 300 ₽…"}'

# 2. обучение — без него знание лежит, но в ответы НЕ попадает
curl -X POST .../chatbots/105/train -d '{}'

# то же с разбором сайта клиента (10 ₽): страница читается и разбивается сама
curl -X POST .../chatbots/105/train -d '{"url":"https://example.com/dostavka","single":true}'

Ответ train содержит knowledge_ready (сколько кусков готово к работе) и failed. Если разбор страницы не удался — деньги возвращаются, и это сказано в тексте ошибки.

Настроить

# витрина бота в Telegram + правила ответов
curl -X PATCH .../chatbots/104 -d '{
  "name": "Кофейня Вайб",
  "description": "Отвечаю на вопросы о меню, доставке и заказах",
  "commands": [{"command": "menu", "description": "Меню и цены"}],
  "instructions": "Ты консультант кофейни…",
  "welcome": "Здравствуйте! Что подсказать?"
}'

# внешний вид виджета на сайте
curl -X PATCH .../chatbots/105/widget -d '{"color":"#7C3AED","position":"right","welcome_title":"Чем помочь?"}'

Названия команд — строчной латиницей (menu, price), описания к ним по-русски: это требование Telegram, и метод отвергнет кириллическую команду до вызова API.

Права ключа

Как и везде в этом API, права выдаются явно: ключ без write на изменение бота получит insufficient_scope, а не молчаливый отказ.

Расходы: куда ушёл каждый рубль — /usage

Обе ручки бесплатные, нужно право read. Считают по журналу операций ключей — те же числа, что человек видит в кабинете на /agent → «Расходы по API» и в выгрузке CSV. Возвраты вычтены, сутки по Москве.

Три уровня в GET /usage:

bonus_expired — не трата: бонусы сгорели по сроку. Не называйте их расходом в отчётах человеку.

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://lk.vibemarketolog.ru/api/agent/usage?days=7"

{
  "status": "ok",
  "days": 7,
  "key": {
    "key_id": 176, "spent": 264, "charged": 390, "refunded": 126, "bonus": 264, "operations": 16,
    "by_category": [{ "category": "direct", "label": "Директ и Метрика", "spent": 220, "operations": 14, "share": 83.3 }],
    "by_model": [{ "model": "gpt-image-2.5-flare-edit", "spent": 44, "operations": 2 }]
  },
  "api": { "spent": 5518, "operations": 76, "by_key": [ … ] },
  "account": { "spent": 6885.03, "services": 6885.03, "purchases": 0, "bonus_expired": 0, "manual_debits": 0 },
  "range": { "from": "…T00:00:00+03:00", "to": "…", "tz": "Europe/Moscow" },
  "history_from": "2026-07-14"
}

Период: days=1 (сегодня по Москве), 7, 30 (по умолчанию), 90, 0 — вся история; старый period=today|week|month тоже понимается. Поля total_spent, total_requests, by_day верхнего уровня оставлены для совместимости и устарели: они складывают все списания аккаунта, включая сгорание бонусов и покупки, не вычитают возвраты и режут сутки по UTC — ответ несёт их перечень в deprecated.

GET /usage/operations — операции от новых к старым. Параметры: scope=key (по умолчанию) или api, days, category (text, image, video, audio, live, wordstat, direct, landing, chatbot, presentation, server, other), limit 1–100 (50), cursor — next_cursor прошлого ответа.

{
  "id": 2932, "at": "2026-09-29T18:11:46+03:00", "kind": "charge",
  "category": "wordstat", "category_label": "Вордстат и семантика",
  "title": "Семантика для сайта (быстрая)", "model": null, "call": "POST mcp",
  "charged": 49, "refunded": 0, "spent": 49, "bonus": 49, "refunds": [],
  "generation_id": null, "transaction_id": 64729,
  "request_id": "8c7d04bc-2bbe-49ee-9f3a-16eb994e7086", "restored": true
}

• Одна операция = списание вместе со всеми его возвратами: резерв текста «списано 30, вернулось 27,40» приходит одной строкой со spent: 2.6. Возврат, у которого списание не найдено, приходит отдельной строкой kind: refund с отрицательным spent.
• request_id совпадает с заголовком ответа исходного вызова — по нему разбирается спорный рубль.
• generation_id есть только у генераций; Вордстат, Директ, лендинги и тексты в /generations не попадают, поэтому их видно только здесь.
• restored: true — операция до 02.10.2026: ключ определён по журналу запросов, а не записан в момент списания. История есть с history_from (журнал запросов хранится 90 дней).

Живой голос — wss /live/sessions (gpt-live-1)

С 24-09-26. Агент сам говорит и слушает во встрече или звонке в реальном времени: слышит собеседников, отвечает голосом, его можно перебить. Думает ваш агент, голос — модель OpenAI gpt-live-1. Ключ OpenAI остаётся у нас, деньги списываются рублями с баланса владельца ключа.

Цена: 15 ₽ за минуту, учёт посекундный (0,25 ₽/с), без округления до минуты.

Порядок

1. POST /live/estimate {"minutes": 45}: бесплатная смета (price_rub, funds_ok, max_minutes_affordable, balance_after, blocker).
2. Открыть WSS. Отказ приходит до соединения с OpenAI обычным HTTP-ответом с JSON {"error":{"code","message","details"}}:

3. Первым приходит наше событие vibe.session.accepted {session_id, mock, models, delegation, price_per_min_rub, tick_s, max_session_s, balance}.
4. Первым отправляете session.start (формат Live API). Прокси проверяет модель и делегирование, дальше события идут как есть в обе стороны: session.input_audio.append, session.update, session.thinking.append, session.commentary.append, session.close → session.started, session.output_audio.delta, session.input_transcript.delta, session.output_transcript.delta, session.delegation.created, session.usage.updated, session.closed.

Делегирование client: как агент отвечает голосом

Проверено вызовами 25-09-26. Когда модели нужны данные или размышления, она сама говорит «сейчас уточню» и присылает session.delegation.created {delegation: {id, target: "client"}}. Ваш агент думает и отвечает событием session.thinking.append {delegation_id, content: "текст ответа"} (или session.commentary.append): модель подтверждает …appended и произносит ответ своими словами. Поле называется content, не text. ⚠️ response.item.create и response.create в режиме client OpenAI отклоняет («requires Responses delegation»), они работают только при delegation: responses. Выход звука идёт непрерывно: в паузах приходят кадры тишины.

session.update принимает только delegation. instructions, audio (голос, формат) и tools получают unknown_parameter: всё это задаётся на session.start, для смены нужна новая сессия. session.instructions.append требует delegation_id, то есть работает только внутри делегирования. Входной звук — session.input_audio.append {audio: base64 PCM16 LE mono}, непрерывно, без commit; пауза — session.input_audio.mute / .unmute.

Служебные события прокси (префикс vibe.)

reason: client_close (вы отправили session.close), client_closed (сокет оборван), balance, daily_limit, max_duration, admin, policy, start_timeout, upstream_closed, upstream_error, upstream_timeout, billing_unavailable, relay_restart.

Коды закрытия сокета: 1000 норма · 4402 деньги · 4429 суточный лимит · 4408 длительность или таймаут старта · 4403 модель или делегирование · 4409 администратор · 1011 сбой поставщика или учёта · 1012 перезапуск сервиса.

В mock можно вызвать события вручную: {"type":"vibe.mock.trigger","event":"delegation"} (придёт session.delegation.created, ответ проверяется как у OpenAI), {"type":"vibe.mock.trigger","event":"low_balance"}, {"type":"vibe.mock.trigger","event":"closing","grace_s":5}. Проверка связи: {"type":"vibe.ping"}, в ответ придёт vibe.pong.

Деньги

• Списание по факту: тик берёт секунды, прошедшие с прошлого тика. При закрытии дописывается остаток (61 с = 15,25 ₽). Возвратов нет, потому что не берём вперёд.
• Секунды считаются от session.started по часам сервера. Повтор тика ничего не списывает дважды, закрытие идемпотентно по session_id.
• Суточный лимит ключа (daily_spend_limit): на старте резервируется 5 минут (75 ₽; если не влезает — 1 минута). Резерв продлевается по ходу разговора, остаток возвращается в лимит при закрытии.
• Если баланс не покрывает следующую минуту, приходит vibe.session.closing reason=balance с паузой на прощание по оставшимся деньгам (до 15 с).
• История: GET /live/sessions/{session_id} отдаёт seconds_total, duration_human («12 мин 34 с»), charged_rub, reason, started_at, ended_at. В ленте операций кабинета строка называется «Живой разговор gpt-live-1 — N мин M с (сессия xxxxxxxx)».

Право live

Новый ключ: галочка «Живой голос» при создании. У существующего ключа право выдаёт владелец платформы командой php artisan agent:scope <почта> live: право добавится всем ключам этого аккаунта (кроме служебных), перевыпускать ключи не нужно.

Мини-пример (Node.js)

const ws = new WebSocket('wss://lk.vibemarketolog.ru/api/agent/live/sessions', {
  headers: { Authorization: 'Bearer ' + process.env.VIBE_KEY },
});
ws.on('message', (m) => {
  const ev = JSON.parse(m);
  if (ev.type === 'vibe.session.accepted') {
    ws.send(JSON.stringify({ type: 'session.start', session: {
      model: 'gpt-live-1', instructions: 'Ты ассистент на встрече. Говори по-русски.',
      audio: { output: { voice: 'marin' } } } }));
  }
  if (ev.type === 'session.output_audio.delta') playPcm16(ev.delta);   // 24 кГц
  if (ev.type === 'vibe.billing.low_balance') sayGoodbyeSoon();
});
// звук встречи: ws.send(JSON.stringify({ type: 'session.input_audio.append', audio: base64Pcm16 }))

Прокси моделей — тело как у поставщика (с 09-10-26)

Для агентов, которым нужен родной формат поставщика: картинки, инструменты (strict), веб-поиск, effort — без перевода в наш /generate. Шлёте тот же JSON, что OpenAI или Anthropic, на наш адрес, ключом oc_… с правом llm:proxy. Ключи поставщиков — наши, оплата в рублях с баланса ключа.

• Ключ: Authorization: Bearer oc_… или x-api-key: oc_… (как шлёт SDK Anthropic). В SDK достаточно сменить base_url на https://lk.vibemarketolog.ru/api/agent/anthropic (или …/api/agent/openai/v1) и подставить ключ oc_….
• Деньги: прайс поставщика × курс 100 ₽/$ × 3, минимум 0,10 ₽ за вызов. Сначала удерживается резерв (худшая цена при потолке вывода), после ответа — факт по токенам, остаток возвращается; если факт выше оценки (крупные картинки, результаты поиска), разница доначисляется. Веб-поиск — 3 ₽ за поиск (у Anthropic не больше 5 на запрос). В ответе поставщика добавлено поле charged_rub и заголовок X-Vibe-Charged-Rub. Ошибка поставщика → резерв возвращается целиком, X-Vibe-Charged-Rub: 0.00.
• Ставки, ₽ за 1M токенов (вход / выход / чтение кеша): Haiku 5.5 — 30 / 150 / 3 (промпт свыше 100K токенов — 150 / 750 / 15 на весь запрос); GPT-6 Luna — 30 / 150 / 3; DeepSeek V4.1 Flash — 90 / 360 / 1,8; Decisions — 30 за 1M входа, вывода нет (решение ~300 токенов, то есть минимальный чек 0,10 ₽).
• Поток (stream: true, с 09-10-26): у Anthropic, OpenAI Responses и DeepSeek — куски поставщика уходят сразу, как пришли (официальные SDK messages.stream, responses.stream, chat.completions.create(stream=True) проверены). Резерв виден в заголовке X-Vibe-Hold-Rub, итог — последней строкой-комментарием SSE : vibe.billing {"charged_rub":0.1,"model":"…"} (SDK её пропускают, свой разборщик читает). Оборвали поток — списываем по факту, сколько поставщик успел сгенерировать; поставщик отказал до потока — обычная ошибка JSON и полный возврат. У Decisions потока нет.
• Одновременность: не больше 4 вызовов прокси и синтеза одновременно на ключ (и 30 на весь прокси) — лишние получают 429 too_many_concurrent (ключ на паузу это не ставит). Лимит частоты — 240 в минуту.
• Документы: блоки document, input_file, file, item_reference пока не принимаются (400) — передавайте текст и картинки. Картинки по ссылке и base64 считаются в резерв как картинки.
• Недобор: если факт выше резерва, а доначислить не вышло (кончились деньги), разница записывается долгом ключа — следующий вызов сначала гасит его, иначе 402 debt_unpaid.
• Поток без итогового расхода (поставщик оборвал до последнего события, а текст уже ушёл) — списывается резерв; ничего не ушло — полный возврат.
• Ограничения: неизвестные поля верхнего уровня — 400 (они могут стоить денег: service_tier, inference_geo, container); из серверных инструментов открыт только веб-поиск. Лимит — 240 вызовов в минуту на ключ и не больше 4 одновременных (см. «Одновременность» выше).
• Хранение у OpenAI (store): по умолчанию выключено — переписка нигде не хранится. store: true сохраняет ответ у OpenAI на 30 дней, и его можно продолжить через previous_response_id, не пересылая историю и снимки экрана. Продолжить можно только СВОЙ ответ (ответ другого аккаунта и несуществующий неотличимы: 404 previous_response_not_found); удалить свой — DELETE …/responses/{id}. Прошлый контекст OpenAI считает входом заново (кешированная часть — по ставке чтения кеша), так что по деньгам это как переслать историю целиком, но быстрее: меньше трафика, и рассуждения модели сохраняются между ходами.
• Замер 09-10-26 через прокси (с нашего сервера): Haiku 5.5 — 1,4 с ответ, 4,8 с картинка + инструмент, 5,1 с веб-поиск; Luna — 1,9 / 1,8 / 3,0 с; DeepSeek — 2,0 / 1,7 с.

Быстрый синтез коротких фраз — POST /tts/stream и POST /tts (с 09-10-26)

Короткие фразы голосами живого разговора (итог поручения, «что сейчас делаю») — дешевле и быстрее /generate type=voice. Право llm:proxy.

• Вход (JSON): text (1–1000 знаков), voice — голос gpt-live-1, instructions (манера речи, до 600 знаков, необязательно).
• Выход: поток сырого PCM16 LE, 24 кГц, моно (Content-Type: audio/pcm). Заголовки: X-Vibe-Charged-Rub (сумма известна заранее — по знакам), X-Vibe-Voice (каким голосом синтезировано).
• Голоса: alloy, ash, ballad, cedar, coral, echo, fable, marin, nova, onyx, sage, shimmer, verse — как есть; голоса только живого разговора ведёт ближайший по высоте тона: delta, gleam → marin; quartz, willow → sage; bossa → ballad; beacon, ripple → cedar; meridian, tempo, vesper → echo; cinder, stone → ash.
• Цена: 6 ₽ за 1000 знаков по факту, минимум 0,10 ₽ (фраза 150 знаков ≈ 0,90 ₽). Отказ поставщика или обрыв потока — полный возврат.
• Два режима: /tts/stream — поток PCM по мере синтеза (первый звук ~1,7–2,8 с); /tts (или "stream": false) — фраза ЦЕЛИКОМ одним ответом с Content-Length (12–13 с речи за ~5 с). Внутри берём у OpenAI Opus и раскодируем в PCM у себя: сырой PCM OpenAI отдаёт нам медленнее, чем он звучит.
• Сбои поставщика: нет звука за 6 с или фраза не пришла за 15 с — повторяем один раз сами; не вышло — 502 provider_unavailable и полный возврат.

Русские голоса ElevenLabs v4 и свой голос — POST /tts с model (с 10-10-26)

Для уведомлений («готов ответ», «нужен ваш ответ») — лучшие русские голоса без акцента или клон своего голоса. Тот же POST /tts (и /tts/stream — с этими моделями фраза приходит одним телом), право llm:proxy.

• Вход (JSON): model, text (1–1000 знаков), voice_id — из GET /voices?language=ru → native_ru[] (носители русского, у каждого preview_url — бесплатный русский образец) или имя/id ElevenLabs; для my-voice — id из GET /voices/my. Необязательно: format (pcm — PCM16 24 кГц моно, по умолчанию; mp3), language_code (ru), манера ElevenLabs — stability, similarity_boost, style (0–1), speed (0,7–1,2; у my-voice 0,5–2).
• Выход: звук одним телом с Content-Length; заголовки X-Vibe-Charged-Rub, X-Vibe-Price-Per-1k, X-Vibe-Model, X-Vibe-Voice.
• Цена: за фактические знаки (без округления до 1000), минимум 0,10 ₽; деньги вперёд, отказ поставщика — полный возврат (502 provider_unavailable, X-Vibe-Provider-Error: 1). Каталог моделей с ценами — GET /voices → tts_models[].
• Скорость (замер 10-10-26): фраза ~90 знаков — синтез ~2–3 с + ~0,9 с доставка; 150–160 знаков — 4–5 с (v4 Turbo), 5–6 с (v4). Свой голос медленнее: ~6–7 с.

Свои голоса аккаунта (право llm:proxy):

• GET /voices/my — голоса аккаунта владельца ключа: id, name, ready, preview_url; там же clone_price_rub.
• POST /voices/clone — multipart: sample (mp3/wav/ogg/webm до 20 МБ, чистая речь 10–300 с), name, consent=true (подтверждение, что голос принадлежит владельцу аккаунта или есть его разрешение — без него 422). Цена — 249 ₽ за голос, при неудаче клонирования — полный возврат. Ответ 201 с voice (id → voice_id для model: my-voice).
• DELETE /voices/my/{id} — удалить свой голос. Чужими голосами синтезировать нельзя (400 invalid_voice).

Яндекс SpeechKit — POST /tts с model: "yandex" (с 10-10-26)

Самый быстрый и дешёвый русский синтез: фраза 150 знаков приходит целиком за ~0,5 с у поставщика (~1 с через наш API), 1000 знаков — за ~5,5 с. 20 голосов носителей русского, у большинства — интонации (role), шесть голосов LiveTTS — живая разговорная речь для поддержки и продаж. Право llm:proxy.

• Вход (JSON): model: "yandex", text, voice (или voice_id) — латинское имя голоса (по умолчанию marina), role — интонация из списка этого голоса (по умолчанию первая), speed (0,5–2,0), format.
• Голоса и интонации — GET /voices → yandex[]: voice, name, gender, live_speech, roles[] (role + название), preview_url (бесплатный образец). Неизвестный голос или интонация, которой нет у голоса, → 400 invalid_voice, ничего не списано.

curl -X POST https://lk.vibemarketolog.ru/api/agent/tts \
  -H "Authorization: Bearer oc_..." -H "Content-Type: application/json" \
  -d '{"model":"yandex","voice":"kirill","role":"strict","text":"Отчёт по рекламе готов.","format":"mp3"}' -o phrase.mp3

Для файла в галерее (а не потока) — POST /generate с type: "audio", model: "yandex-tts", voice_id, role, speed: 3 ₽ за каждую начатую 1000 знаков (как в кабинете), до 5000 знаков, результат готов за ~1 с.

Живой голос: ровность звука в итоге сессии (с 09-10-26)

В vibe.session.closed есть upstream_audio: chunks, audio_s, gaps_over_200ms (паузы между кусками ВНУТРИ фразы, 200 мс–2 с), gap_max_ms, underruns_480ms_cushion, underrun_total_ms, underrun_max_ms — замер на входе релея от OpenAI, до сети к агенту. Звук не хранится. Работает и в ?mock=1.

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

POST /generate

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

⚠️ type: "text" работает иначе остальных: он синхронный и тарифицируется по фактическим токенам. Ответ приходит в том же запросе (никакого поллинга), а деньги списываются не фикс-ценой, а по реальному расходу — см. раздел «Текстовые модели». Все остальные типы — асинхронные, с generation_id и опросом статуса.

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

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

Ответ

{
  "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
  "stage": "complete",            // ЕДИНОЕ поле состояния async-задачи на всех эндпоинтах (generation, voice/status, voiceover/long) — опрашивайте именно его
  "generation_id": 5811,
  "task_id": "task_xxx",
  "model": "grok-itv",
  "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,
  "price_rub": 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 провайдера, протухает; использовать не рекомендуется.

Каталог моделей и цен

Перечень ниже собирается из контракта командой php artisan agent:docs-sync и им же проверяется (--check): это тот же источник, что отдаёт GET /capabilities, поэтому число моделей и цена здесь и в API совпадают по построению, а не по внимательности редактора. Разделы ниже — примеры запросов и подводные камни — остаются рукописными.

Две модели полезно знать до чтения таблицы, потому что они меняют смету в разы: grok-image-2 (3 ₽ за картинку — в шесть раз дешевле соседей по качеству) и gpt-6-luna (30/150 ₽ за 1M токенов — в 20 раз дешевле gpt-6.1-sol на входе).

Модель по умолчанию для изображений — GPT-Image-2.5

Рекомендуем назначать gpt-image-2.5-flare моделью по умолчанию и для создания, и для редактирования изображений. Так же настроен встроенный агент платформы.

Почему именно она:

• русский текст без опечаток — шесть текстовых блоков в одном макете воспроизводятся дословно, включая мелкий шрифт (проверено живыми генерациями);
• дешевле предыдущего поколения — 16 ₽ против 19 ₽ у gpt-image-2;
• правка меняет только названное — лица, фон и надписи вокруг остаются нетронутыми даже через несколько итераций подряд;
• прозрачный фон (background: transparent) с настоящим альфа-каналом — для логотипов, мерча и элементов под вёрстку;
• быстрая — 18–26 секунд на картинку.

Когда брать gpt-image-2.5-sunburst: те же деньги (16 ₽), ответ дольше (22–38 с), но выше точность при серии правок — для финальных макетов под публикацию и товарной съёмки.

Для редактирования используйте -edit-варианты того же слага. Если передать image_input в обычный слаг, запрос сам уйдёт в режим правки — референсы не теряются.

Пропорции (обновлено 09-09-26). Доступны auto, 1:1, 16:9, 9:16, 4:5, 3:2, 4:3, 3:4, 5:4, 2:3, 21:9. 16:9 и 9:16 — родные, без подмены на 3:2/2:3 (прежнее ограничение было нашим и снято после замера живыми вызовами). Значение по умолчанию — auto: с image_input оно сохраняет пропорции присланного фото, без image_input кадр подбирает модель по смыслу запроса.

Рекомендуемый набор из трёх ступеней

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

Ставьте gpt-image-2.5-flare по умолчанию, а sunburst — как задел «если нужно ещё лучше». Уходить с 2.5 ради пропорции больше не нужно: все ходовые форматы у неё родные.

Правка готового изображения — -edit-варианты семейства 2.5 (22 ₽): они меняют только названное. У grok-image-2 правки по чужому файлу нет вовсе — он умеет дорабатывать лишь собственную прошлую генерацию.

Остальные модели каталога никуда не делись и доступны по имени — набор выше про то, что предлагать по умолчанию, а не про ограничение.

Подробный разбор всех режимов — в навыке gpt-image-25 (GET /api/agent/skills/gpt-image-25).

Всего моделей: 72 (изображения 32, видео 22, голос и озвучка 10, музыка 4, текст (оплата по токенам) 4). Цена — та, что спишет POST /generate при дефолтных параметрах. Точная сумма конкретного запроса всегда бесплатна: POST /generate/estimate.

Изображения — 32

Видео — 22

Голос и озвучка — 10

Музыка — 4

Текст (оплата по токенам) — 4

Снятые модели. gpt-image-1.5 остаётся в каталоге ради совместимости, но провайдер её выключил: 146 попыток, ноль успехов. Запрос по этому имени выполняется на gpt-image-2 (19 ₽), а с image_input — на gpt-image-2-edit (22 ₽); смета возвращает цену фактического исполнителя, поэтому бюджет считайте по ней. В новых интеграциях называйте gpt-image-2.5-flare — она дешевле (16 ₽), сильнее по русскому тексту и умеет прозрачный фон.

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

⚠️ 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",
    "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 с 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",
    "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 / grok-itv — ступень тарифа выбирается по duration автоматически (≤6 с, 7–10 с, 11–15 с), вы платите ровно за свою длительность. Точная сумма до списания — POST /generate/estimate; границы ступеней — tier_bounds в /capabilities. Имена с числовым суффиксом (grok-ttv-10 и подобные) оставлены только для совместимости со старыми интеграциями и в новых не используются: они берут фиксированную цену ступени независимо от длительности. Форматы (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.5 (ByteDance) — флагман семейства, посекундно

Старший тир Seedance, сменивший Seedance 2.0 в кабинете (17-08-2026). Ролик до 30 секунд одним куском, до 1080p, нативный AI-звук, до 9 reference images, до 3 reference videos / audio, first_frame_url / last_frame_url для image-to-video, aspect_ratio ещё и adaptive, output_format — mp4 или mov. Модель: seedance-2-5.

Цена — посекундная: 480p 20 ₽/сек, 720p 45 ₽/сек, 1080p 82 ₽/сек. Без duration и resolution заказывается минимальный ролик — 4 секунды в 720p (180 ₽).

⚠️ Видео-референс меняет ФОРМУЛУ, а не даёт скидку. С reference_video_urls действует пониженная ставка (480p 13, 720p 28, 1080p 49 ₽/сек), но она умножается на сумму секунд исходника и результата: (input + output) × rate. Длинный исходник делает короткий ролик дороже, чем генерация вообще без референса. Референсные видео обязаны быть загружены через POST /api/agent/upload-media — их длительность мы измеряем сами, суммарно не больше 30 секунд. Точная сумма до списания — POST /generate/estimate.

Все ставки машиночитаемо: GET /capabilities → поля per_second_by_resolution и per_second_by_resolution_with_video_input.

# Ролик 10 секунд в 720p (450 ₽)
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-5",
    "prompt": "stylish young woman walking through neon-lit Tokyo street at night, slow motion",
    "aspect_ratio": "9:16",
    "duration": 10,
    "resolution": "720p",
    "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-5",
    "prompt": "the model starts walking towards the camera, smiles",
    "first_frame_url": "https://lk.vibemarketolog.ru/uploads/agent/...",
    "duration": 6,
    "resolution": "1080p",
    "aspect_ratio": "9:16"
  }'

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

• voiceover_text — реплика. Ограничение: 13,5 знака в секунду ролика (10 с = 135 знаков). Более длинный текст отклоняется до списания с ошибкой bad_input и объяснением.
• voiceover_voice — голос: Leda, Kore, Sulafat (женские), Puck, Charon, Orus (мужские). По умолчанию Leda.
• voiceover_model — gemini-flash-tts (по умолчанию) или gemini-pro-tts.

Цена — отдельным слоем: 13 ₽ за каждую начатую тысячу знаков сверх стоимости видео. Если синтез не удастся, стоимость слоя вернётся на баланс, а ролик придёт без голоса — за снятое видео деньги не теряются.

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-5",
    "prompt": "Cozy coffee shop, steam rising over a cup, warm morning light, slow push-in",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "9:16",
    "voiceover_text": "Свежая обжарка каждое утро. Заходите на чашку.",
    "voiceover_voice": "Leda"
  }'

Ограничения: prompt до 30000 знаков, duration 4–30 с, max 9 reference images, max 3 reference videos (суммарно ≤30 с), max 3 reference audio. first_frame_url/last_frame_url и reference_image_urls — взаимоисключающие сценарии, отправляйте что-то одно.

Seedance 2.0 / Fast (ByteDance) — снята с витрины

Убрана из интерфейса кабинета 17-08-2026 в пользу Seedance 2.5, но продолжает работать по API для уже интегрированных агентов. Cinematic-видео, 4-15 сек, до 9 reference images, до 3 reference videos / audio, first_frame_url и last_frame_url для image-to-video. Для новых интеграций берите seedance-2-5: она дешевле на коротких роликах и умеет до 30 секунд.

# 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.

MiniMax H3 (Hailuo 03) — 2K со встроенным звуком

Флагман MiniMax: видео 2560×1440 со встроенной стереодорожкой — звук генерируется вместе с картинкой в одном проходе, отдельная озвучка не нужна. Длительность 4–15 с, prompt до 7000 знаков. Модель: minimax-h3.

Биллинг: per-second, 37 ₽/сек. Полная формула провайдера:

цена = 37 ₽ × (длительность результата + длительность ВХОДНОГО видео) + 11 ₽ × (изображений сверх 5)

Аудио-референсы бесплатны. Точную сумму до списания всегда отдаёт POST /generate/estimate.

Три режима — параметр h3_mode:

Режим определяется по фактическому составу входов, а не только по слову клиента: если прислать видео или аудио, запрос уйдёт как reference, даже когда в h3_mode указан text — присланные файлы не выбрасываются молча.

# Режим reference: движение камеры из видео, персонаж из фото, голос из аудио
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "minimax-h3",
    "h3_mode": "reference",
    "prompt": "Возьми движение камеры из Видео 1, персонажа из Изображения 2, голос из Аудио 3",
    "reference_video_urls": ["https://lk.vibemarketolog.ru/uploads/agent/.../camera.mp4"],
    "reference_image_urls": ["https://lk.vibemarketolog.ru/uploads/agent/.../hero.jpg"],
    "reference_audio_urls": ["https://lk.vibemarketolog.ru/uploads/agent/.../voice.mp3"],
    "duration": 10,
    "aspect_ratio": "16:9"
  }'

Форматы: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, а в режиме reference ещё и adaptive (пропорции исходника).

Ограничения и подводные камни:

• prompt до 7000 знаков — длиннее отклоняется ДО списания.
• До 9 изображений, до 3 видео, до 3 аудио в одном запросе. Первые 5 изображений бесплатны.
• Видео-референс должен быть загружен через POST /api/agent/upload-media. Ссылку на чужой домен модель не примет: его длительность нельзя измерить, а она входит в цену, поэтому такой запрос отклоняется с IncompatibleParams до списания.
• Суммарная длина видео-референсов — не больше 60 секунд.
• reference_audio_urls не работает в одиночку: рядом должно быть изображение или видео.
• Точную стоимость с учётом входного видео и лишних картинок возвращает POST /generate/estimate.

PixVerse V6 — пять режимов и самый дешёвый тариф каталога

Секунда видео от 4 ₽ — самая доступная видео-модель API. Звук генерируется вместе с картинкой (generate_audio: true), длительность 3–15 с, prompt до 5000 знаков, разрешение 360p / 540p / 720p / 1080p. Модель: pixverse-v6.

Биллинг: per-second, тариф — пара «разрешение + звук»:

Цена = тариф × duration. Режим на цену не влияет: extend оплачивает только запрошенные секунды продолжения, а не длину исходника. Точную сумму до списания отдаёт POST /generate/estimate.

Пять режимов — параметр pv_mode:

pv_mode можно не указывать — режим выводится из фактического состава входов. aspect_ratio (16:9, 4:3, 1:1, 3:4, 9:16, 2:3, 3:2, 21:9) применяется только в text и reference: в остальных режимах пропорции берутся из исходника.

# Сцена по референсам: имена Image1…Image7 присваиваются автоматически по порядку
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "pixverse-v6",
    "pv_mode": "reference",
    "prompt": "Персонаж с @Image1 берёт товар с @Image2 и улыбается в камеру",
    "image_references": [
      "https://lk.vibemarketolog.ru/uploads/agent/.../hero.jpg",
      "https://lk.vibemarketolog.ru/uploads/agent/.../product.jpg"
    ],
    "duration": 8,
    "resolution": "720p",
    "generate_audio": true,
    "aspect_ratio": "9:16"
  }'

Ограничения и подводные камни:

• Референсы адресуются из промпта как @Image1, @Image2… Имена присваиваются по порядку массива автоматически; ссылка на несуществующий номер просто игнорируется моделью.
• В image уходит только первая картинка: с несколькими провайдер требует template_id (каталога шаблонов у нас нет) и отвечает ошибкой.
• extend по parent_task_id работает только со своей завершённой генерацией pixverse-v6 — чужой task_id отклоняется до списания. Для чужого или внешнего видео используйте video_url файла, загруженного через POST /api/agent/upload-media.
• multi_clip: true (мультисцена) доступен только в text и image — в остальных режимах поле не отправляется провайдеру.
• pv_seed (0–2147483647) фиксирует результат; в transition и extend seed отправляется всегда, без него провайдер принимает задачу и роняет её.
• Лишние для режима поля отбрасываются до отправки: провайдер отвечает 422 на поле не из своего контракта, а деньги к этому моменту уже списаны.

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-рендер оплачивается отдельно при подтверждении.

Текстовые модели (type=text)

Добавлено 29-07-2026. Синхронная генерация текста флагманскими моделями. Оплата — по фактическим токенам, а не фикс-ценой за вызов: у текста нет заранее известного «размера ответа».

Чем отличается от остальных типов:

Модели и ставки (живой список с ценами — GET /capabilities → text_models):

Ориентир: промпт на 1000 токенов с ответом на 300 токенов — около 3 ₽ (Opus 5.5), 1.5 ₽ (GPT-6.1 Sol) и копейки (GPT-6 Luna, но минимум за вызов 0.5 ₽).

Снятые модели (22-09-26). claude-opus-5, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna из каталога убраны, но запрос по их имени (в том числе с префиксом chat-) принимается и выполняется преемником: Opus 5 → claude-opus-5-5, Sol и Terra → gpt-6.1-sol, Luna → gpt-6-luna. Цена — по ставкам преемника, поле model в ответе называет его. С 09-10-26 так же снят gpt-6-sol: запрос по этому имени выполняет gpt-6.1-sol — те же 600 / 3000 ₽ за 1M, а чтение кеша вдвое дешевле (30 ₽ против 60 ₽). Вход длиннее 272 000 токенов у OpenAI дороже — 1200 / 4500 ₽ за 1M (кеш 60 ₽), считаем по этой ставке. У claude-opus-5-5 размышления не отключаются: thinking:false просто не включает показ, экономить — через effort.

Поля запроса:

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "model": "claude-opus-5-5",
    "system": "Ты копирайтер. Пиши по-русски, без эмодзи.",
    "prompt": "Пост для телеграм-канала кофейни про сезонный напиток, 2 абзаца.",
    "max_tokens": 1500
  }'

Ответ:

{
  "status": "complete",
  "generation_id": 26118,
  "type": "text",
  "model": "claude-opus-5-5",
  "text": "Осень пришла в наше меню: встречайте тыквенный латте…",
  "stop_reason": "end_turn",
  "usage": { "input": 69, "output": 289, "cache_read": 0, "cache_write": 0 },
  "cost": 2.28,
  "reserved": 11.48,
  "refunded": 9.2,
  "balance_after": 5977.25
}

Как читать деньги в ответе: reserved — сколько заняли на время работы, cost — сколько реально списали, refunded — сколько вернули на баланс в этом же вызове. Дневной лимит ключа расходуется на cost, а не на reserved.

Смета до списания (бесплатно): POST /generate/estimate с type: "text" возвращает reserve_rub (верхняя граница), estimated_input_tokens, ставки rub_per_1m и предупреждения — например, что промпт длиннее лимита или что резерв не проходит по дневному лимиту ключа.

Что нужно знать:

• stop_reason: "max_tokens" — ответ обрезан по потолку; повторите с бо́льшим max_tokens.
• Промпт длиннее ~60 000 входных токенов отклоняется с prompt_too_long до любого списания.
• Не хватает баланса на минимальный ответ — 402 insufficient_balance, ничего не списано.
• Почта не подтверждена, а платить нечем кроме бонусных рублей — 402 email_confirmation_required с текстом причины и charged: 0. Подтвердите адрес в кабинете либо пополните баланс — и вызов пройдёт.
• Сбой провайдера — 502 text_generation_failed, резерв возвращается целиком.
• Результат сохраняется в историю генераций (GET /generations, type: "text"), текст лежит в поле text_content.

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

Изображения

# 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).

# Qwen Image 3.0 (Alibaba) — 2K по цене 1K, ровный текст на картинке
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "qwen-image-3",
    "prompt": "витрина кофейни, меловая доска с надписью «КОФЕ 149 ₽», тёплый свет",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "output_format": "png",
    "negative_prompt": "водяные знаки, лишние надписи",
    "seed": 12345,
    "prompt_extend": true
  }'
# ⚠️ prompt ≤ 800 символов — длиннее отклоняется ДО списания.
# resolution 1K|2K стоит одинаково → берите 2K. prompt_extend=true (по умолчанию):
# модель сама разворачивает короткое описание. seed: 0..2147483647, один и тот же
# сид даёт близкие кадры (серия в одном стиле). Старшая версия — qwen-image-3-pro.

# Qwen Image 3.0 Edit — редактирование по 1–10 картинкам (или qwen-image-3-pro-edit)
curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "image",
    "model": "qwen-image-3-pro-edit",
    "prompt": "замени содержимое постера на витрине, остальное не трогай",
    "image_input": ["https://lk.vibemarketolog.ru/uploads/agent/..."],
    "resolution": "2K"
  }'

# 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 модели + Google Gemini TTS — 2 модели)

Модели ElevenLabs:

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

Модели Google Gemini TTS (одиночная озвучка + диалоги, 30 фирменных голосов, эмоции тегами в тексте — см. раздел «Gemini TTS» ниже):

• gemini-flash-tts (Gemini 3.1 Flash TTS — посимвольно: 13₽ за каждую начатую 1000 знаков) — быстрая озвучка с живыми интонациями. До 5000 знаков за запрос; больше — авто «длинная озвучка»
• gemini-pro-tts (Gemini 2.5 Pro TTS — посимвольно: 18₽ за каждую начатую 1000 знаков) — студийное качество. Те же параметры и голоса, что у Flash

⚠️ ВАЖНО про выбор голоса. Чтобы голос отличался от стандартного, в КАЖДОМ запросе передавайте 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. Цена та же посимвольная (8₽ за каждую начатую 1000 знаков от полного текста: 14 920 знаков = 120₽), списывается при старте, при ошибке возвращается автоматически.

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

{
  "status": "processing",
  "long_voiceover": true,
  "voiceover_id": 12,
  "chars": 14920,
  "chunks": 4,
  "cost": 120,
  "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
  }'

Gemini TTS (Google — озвучка и диалоги)

gemini-flash-tts (13₽/1000 знаков) и gemini-pro-tts (18₽/1000 знаков) — синтез речи Google с 30 фирменными голосами, живыми интонациями и эмоциями прямо в тексте. Обе модели умеют одиночную озвучку (1 голос) и диалог (1–2 голоса). Тариф посимвольный — как у el-tts-turbo, но 13/18₽ за начатую 1000 знаков. Лимит 5000 знаков за запрос; больше — авто «длинная озвучка» (см. ниже, voiceover_id+status_url).

30 голосов: Zephyr, Puck, Charon, Kore, Fenrir, Leda, Orus, Aoede, Callirrhoe, Autonoe, Enceladus, Iapetus, Umbriel, Algieba, Despina, Erinome, Algenib, Rasalgethi, Laomedeia, Achernar, Alnilam, Schedar, Gacrux, Pulcherrima, Achird, Zubenelgenubi, Vindemiatrix, Sadachbia, Sadaltager, Sulafat. По умолчанию — Zephyr.

Параметры (все опциональны, кроме prompt):

• voice_name — один из 30 голосов (одиночная озвучка).
• style — стиль подачи, только Deadpan | Whisper | Newscaster.
• temperature — 0.0–2.0, «живость» интонаций.
• scene — атмосфера сцены (до 1000 знаков), sample_context — тон/контекст (до 1000 знаков).
• Эмоции — inline-теги в самом тексте: [радостно] Привет! [шёпотом] секрет.
• Диалог — массивы speakers[] (до 2 спикеров) и dialogue_turns[].

Одиночная озвучка:

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "voice",
    "model": "gemini-flash-tts",
    "prompt": "[радостно] Привет! [шёпотом] А теперь маленький секрет.",
    "voice_name": "Zephyr",
    "style": "Deadpan",
    "temperature": 1
  }'

Диалог (1–2 голоса):

curl -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "voice",
    "model": "gemini-pro-tts",
    "prompt": "placeholder",
    "speakers": [
      {"speaker_id": "Speaker 1", "voice_name": "Puck", "style": "Newscaster"},
      {"speaker_id": "Speaker 2", "voice_name": "Kore", "style": "Deadpan"}
    ],
    "dialogue_turns": [
      {"speaker_id": "Speaker 1", "text": "[воодушевлённо] Привет! Как продвигается запуск?"},
      {"speaker_id": "Speaker 2", "text": "[спокойно] Отлично, уже почти всё готово."}
    ]
  }'

Длинная озвучка (prompt > 5000 знаков) работает и для gemini-flash-tts/gemini-pro-tts — тот же посимвольный тариф (13/18₽/1000 от полного текста), тот же ответ voiceover_id+status_url (см. «Длинная озвучка» выше). Точная смета — через POST /generate/estimate и GET /prices.

Мой голос — my-voice-tts (10₽/1000 знаков)

Озвучка текста голосом, клонированным в личном кабинете (MiniMax). Обязательные поля: prompt (текст, ≤5000 знаков) и cloned_voice_id — id вашего клонированного голоса; опционально speed (0.7–1.2). Голос обязан принадлежать владельцу API-ключа, иначе отказ «Голос не найден» с возвратом. Списание — за каждую начатую 1000 знаков (10 ₽), см. per_1000_chars в GET /prices.

Яндекс SpeechKit — yandex-tts (3₽/1000 знаков)

20 русских голосов Яндекса с интонациями: prompt (≤5000 знаков), voice_id — латинское имя голоса (marina по умолчанию), role — интонация голоса, speed (0.7–1.2). Неверная пара голос+интонация отклоняется до списания (422 bad_input). Списание — за каждую начатую 1000 знаков (3 ₽). Голоса и интонации — GET /voices → yandex[]; таблица — в разделе «Яндекс SpeechKit — POST /tts» выше.

Длинный текст (с 11-10-26). prompt длиннее 5000 знаков (до 200 000) обрабатывается как длинная озвучка — так же, как у gemini-*-tts и el-tts-turbo: текст режется по предложениям на куски до 4000 знаков, озвучивается выбранным голосом и интонацией и склеивается в один mp3. Вместо generation_id ответ вернёт voiceover_id и status_url (GET /api/agent/voiceover/long/{id}); кусок в 4000 знаков готов примерно за 30 с (замер: 5216 знаков — 54 с целиком). Цена та же — 3 ₽ за каждую начатую 1000 знаков всего текста, при сбое — полный возврат. Неверная пара голос+интонация → 422 bad_input до списания.

curl -s -X POST https://lk.vibemarketolog.ru/api/agent/generate \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"audio","model":"yandex-tts","prompt":"<текст на 5000+ знаков>","voice_id":"irina","role":"narrator"}'
# → {"status":"processing","long_voiceover":true,"voiceover_id":30,"chunks":2,"cost":18,"status_url":"…/voiceover/long/30"}

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

# Все голоса (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 / ?has_preview=1) в API пока не отдаются — характер голоса описывает поле style, а звучание на русском проверяйте по gender_ru/recommended_ru ниже.

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

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

Расхождения не единичные: у части голосов метка провайдера противоположна тому, что слышно на русском. Поимённые результаты замеров — в ответе GET /voices, поле recommended_ru (male / female / avoid) и f0_ru_hz по каждому голосу. Списки поддерживаются нами и обновляются по мере новых замеров, поэтому берите их из эндпоинта, а не переписывайте в свой код.

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

• Модель — 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, verified_ru}'

# Озвучить гарантированно мужским голосом на русском:
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"
# → {"stage":"success","validate_info":"Произнесите: ...","task_status":"success"}  // опрашивайте stage

Шаг 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"
# → {"stage":"complete","voice_id":"persona_xyz","task_status":"complete"}  // stage — единое поле опроса

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

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",
  "status": "complete",
  "result_url": "https://...",
  "result_urls": ["https://..."],
  "cost": 196.0,
  "price_rub": 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,
  "delivery_id": "dlv_...",          // стабильный id ДОСТАВКИ: одинаков у всех повторов одного события — ключ дедупликации
  "timestamp": 1770000000,           // unix seconds, момент отправки
  "sent_at": "2026-08-11T01:50:34+03:00",
  "signature_scheme": "webhook_secret",  // либо "legacy_token_hash" = sha256(raw_token) у ключей до 09.07.2026
  "signature_version": 1,
  "delivery_semantics": "at-least-once", // возможны повторы (tries=3, backoff 30/120/600)
  "freshness_window": 600                // рекомендованное окно свежести, секунд
}

Анти-replay поля (delivery_id/timestamp/signature_scheme и их заголовки-дубли) присутствуют в обоих контурах — генерации и agent.message. Источник истины — поля ВНУТРИ тела (оно под подписью); заголовки — удобство до разбора JSON и подделываются, сверяйте их с телом. Рекомендуемый порядок на вашей стороне:

1. hmac_sha256(raw_body, secret) === X-Vibe-Signature — иначе отбросить;
2. now − payload.timestamp > 600 — отбросить как устаревшее (защита от replay);
3. дедуплицировать по payload.delivery_id — доставка at-least-once, повтор несёт тот же id (не путать с generation_id: у одной генерации бывает несколько событий).

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

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

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).

Не сохранили секрет или ключ старый? Кабинет → «API-ключи» → кнопка с круговой стрелкой у нужного ключа. Секрет перевыпускается отдельно от ключа доступа: агент продолжает работать, меняется только значение для проверки подписи. Показывается один раз, прежний умирает сразу — обновите его в конфиге обработчика вебхуков.

Пример 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) {
  if (typeof headerSignature !== 'string' || headerSignature.length === 0) return false;
  const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(headerSignature, 'utf8');
  // timingSafeEqual бросает исключение при разной длине буферов — сначала сверяем длину.
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

Для легаси-ключа замените 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."
}

Единый формат ответа об ошибке

Любая ошибка публичного API приходит в одной схеме — её достаточно разобрать один раз:

{
  "status": "error",
  "error": "validation_failed",
  "message": "Поле model обязательно для заполнения. Всего ошибок в запросе: 2 — подробности в поле details.",
  "details": {
    "model": ["Поле model обязательно для заполнения."],
    "type": ["Выбранное значение для type некорректно."]
  },
  "request_id": "0f9c8b7a-2d41-4e6b-9c3a-1b5f7e2d8a04"
}

Обратная совместимость: у ошибок валидации рядом с details остаётся прежний ключ errors, у 403 insufficient_scope — прежние required и granted, у 402 — required/balance. Существующие интеграции ломать не нужно.

Коды ошибок

Повторы запросов: обязательное правило

Любой ответ 429 и 503 содержит retry_after (и заголовок Retry-After) — ждите указанное время, не повторяйте раньше. Повтор без задержки приводит к key_cooling_down: если у ключа 80 % и больше ответов в пятиминутном окне — серверные сбои или отказы по лимиту (при 20+ обращениях), ключ уходит на паузу от 5 до 30 минут. Ошибки 4xx (валидация, права) на паузу не влияют — по ним можно спокойно исправлять запрос.

Рабочая схема: пауза 1 с → 2 с → 4 с → 8 с, не больше 5 попыток, затем остановка и сообщение человеку. Для долгих операций опрашивайте статус не чаще раза в 10–20 с, а лучше подпишитесь на вебхук (POST /webhook-url) и не опрашивайте вовсе.

Тексты ошибок сознательно не содержат внутренних подробностей (имён классов, таблиц, поставщиков моделей, путей файлов): для диагностики служит request_id.

При ошибке 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,
  "body_valid": true,
  "funds_ok": true,
  "dry_run": true,
  "model": "veo3_fast",
  "type": "video",
  "estimated_cost_rub": 120,
  "price_rub": 120,
  "applied_tier": null,
  "balance": { "current": 1049, "after": 929 },
  "balance_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": [],
  "param_rejections": [],
  "param_adjustments": [],
  "params_validated": true,
  "value_warnings": [],
  "misrouted_media": null,
  "valid_params": ["type","model","prompt","..."],
  "warnings": []
}

price_rub — каноническое поле цены во всех ответах (смета, запуск /generate, статус): используйте именно его для предохранителя бюджета, оно есть везде (estimated_cost_rub/cost оставлены для совместимости). balance_after — остаток после списания, тоже единым именем во всех ответах.

body_valid / funds_ok — раздельные признаки: «тело запроса корректно» и «денег/лимита хватает». valid остаётся их конъюнкцией: по valid:false смотрите, ЧТО чинить — запрос (body_valid:false) или баланс (funds_ok:false).

applied_tier — применённая ступень тарифа для ступенчатых моделей ({key, fixed, bounds}): grok-ttv/itv по duration, gemini-omni-video по resolution, seedream-5-pro по quality. fixed:true = позван легаси-ключ с закреплённой ступенью, duration на цену не влияет. null — у модели нет ступеней. Границы ступеней публикует tier_bounds в /capabilities.

param_rejections — значения параметров, которые модель заведомо отвергнет (напр. aspect_ratio:4:5 у z-image): при непустом списке valid:false, в каждом элементе есть hint с допустимыми значениями — запрос не начинайте, замените значение. param_adjustments — значения, которые платформа молча приведёт к рабочим (напр. output_format:jpeg → png): запрос пройдёт, но результат будет в приведённом варианте.

value_warnings — значение не входит в объявленный enum модели ({field, value, allowed, note}): запрос НЕ отклоняется, но исполнитель может молча взять дефолт/дешёвую ступень («заказал 4K — получил 720p»). Сверьте с applied_tier и почините значение. params_validated:false — модели нет в каталоге, поля запроса вообще не проверялись: «valid» ≠ «параметры проверены».

misrouted_media — медиа-поле, которое эта модель НЕ принимает, и правильное поле вместо него ({field, use_instead[]}): без исправления генерация уйдёт без вашего медиа, а деньги спишутся.

Несуществующий тарифный ключ (grok-ttv-40) — valid:false в смете, а /generate ответит 422 unknown_price_tier (раньше такой ключ проходил «годным» с ценой 0 ₽).

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

Приёмка результата — блок acceptance (бесплатно)

Пришлите вместе с POST /generate машинопроверяемые критерии — по готовому файлу платформа выполнит детерминированные проверки и отдаст вердикт в GET /generation/{id}/status (поле acceptance). Кто спеку не прислал — получает прежний ответ байт в байт. Вердикт информационный: статус генерации и деньги не меняет.

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":"логотип на белом фоне","strict":true,
       "acceptance":{"format":"png","aspect_ratio":"1:1","aspect_ratio_tolerance":0.02,"min_width":1024,"not_blank":true}}'

Поддерживаемые проверки (только исполняемые, список — в /capabilities → acceptance.checks): format (png/jpg/jpeg/webp/gif/mp4/mov/mp3/wav), aspect_ratio "W:H" + aspect_ratio_tolerance (относительный, дефолт 0.02; только изображения), min_width/min_height (px, только изображения), max_file_size_mb, min_file_size_kb, not_blank.

Ответ статуса (только приславшим спеку):

"acceptance": {
  "status": "partial",              // passed | partial | failed | skipped | pending (ещё не complete)
  "checks": [ {"check":"format","passed":true,"actual":"png","expected":"png"},
              {"check":"aspect_ratio","passed":false,"actual":"1024x768 (1.3333)","expected":"1:1 ±0.02"} ],
  "failed_checks": ["aspect_ratio"],
  "unsupported": [],                // ключи спеки, которые платформа исполнить не умеет — честно перечислены
  "note": "Informational verdict: it does not change the generation status or billing."
}

Проверки для видео/аудио ограничены файловыми (format, размеры файла, not_blank) — проверки кадра помечаются passed:null и в вердикт не входят.

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","X-Vibe-Timestamp","X-Vibe-Delivery-Id","X-Vibe-Signature-Scheme"],
  "payload_sent": { "event": "webhook.test", "...": "..." }
}

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

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

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

Ближе всего к точечной правке семейство gpt-image-2.5-*-edit (сентябрь 2026): оно меняет только то, о чём просят, и не разрушает лица, фон и надписи вокруг. Формально это по-прежнему художественная правка — preserves_input: false, — но на практике потери вне названной области минимальны.

Входящие сообщения (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/.

Brand Voice — профиль бренда для генераций

Профиль бренда хранит тон, аудиторию, палитру, стоп-слова, фирменный голос и продукты. Передайте brand_id в /generate — и поля профиля подставятся автоматически, но только те, которые принимает схема конкретной модели (GET /capabilities): параметры из запроса всегда выигрывают, ценовые поля (quality/duration/resolution) не подставляются никогда, prompt озвучки и музыки не трогается.

С 20-10-26 запись профилей бренда принимает право generate наравне с write: бренд — бесплатная настройка генераций того же аккаунта, и агенту с ключом generate не нужен общий write, чтобы создать бренд, переключить или выключить активную пару. Остальные методы под write (чат-боты, переписка, вебхук) по-прежнему требуют write. Лимит записи — 10 запросов в минуту на ключ.

Поля бренда: name* , industry, description, website, tagline, target_audience, tone_of_voice, avoid_words, palette (массив #RRGGBB, ≤8), voice_id (из GET /voices), voice_model, defaults ({aspect_ratio, output_format, image_model, video_model, audio_model}), reference_images (≤5 URL). Лимиты: 10 брендов / 50 продуктов на аккаунт.

Параметры генерации: brand_id (чужой → 422 brand_not_found ДО списания), product_id (продукт того же бренда), brand_apply: false — отключить инжект даже при активном бренде. Если brand_id не передан, применяется активная пара аккаунта (POST /brand/activate).

Смета бесплатна: POST /generate/estimate с brand_id возвращает applied_brand_fields[] — ровно то, что будет подставлено, без списания. Ответ /generate содержит то же поле.

FAQ для агентов

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

Q: Как использовать image-to-video для Grok? A: Модель grok-itv (Grok 1.5 Preview, базовое имя — тир цены по duration) + ровно один 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. Учтите: доступы к внешним сервисам отдаются только под отдельный scope yandex — не добавляйте его без необходимости. Полные права (write/autopilot/yandex) выдавайте только проверенным агентам.

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

Документ обновляется при изменениях API. Последнее обновление: 2026-09-07 (исправлены цены озвучки ElevenLabs, перечень моделей и цен теперь собирается из контракта командой agent:docs-sync). Связь с поддержкой: @centrmedia.

Программное управление рекламой

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

Оставить заявку (имя и контакт, ответим в рабочее время): https://vibemarketolog.ru/api#lead

Или напишите напрямую: @centrmedia

Журнал обновлений

Формат: одна запись — одна строка, дата в начале. Раньше журнал был одним абзацем на 3950 знаков с тринадцатью суммами подряд, и цена соседней записи читалась как цена вашей модели: seedream-5-pro (25/40 ₽) стояла рядом с семёркой и четырнадцаткой от qwen-image-3. Так же оставались без своей цены ещё одиннадцать моделей. Цены моделей теперь живут в разделе «Каталог моделей и цен», который собирается из контракта.

• 2026-10-02 — Расходы по ключам: GET /usage получил блоки key (этот ключ), api (все ключи аккаунта) и account (работа, покупки, сгоревшие бонусы — раздельно), возвраты вычтены, сутки по Москве; новая ручка GET /usage/operations — каждая платная операция с возвратами и request_id, включая Вордстат, Директ, лендинги и тексты; инструмент MCP get_usage. Старые поля /usage сохранены и помечены устаревшими.
• 2026-09-09 — Добавлено семейство GPT-Image-2.5 (OpenAI, релиз 08-09-26): gpt-image-2.5-flare и gpt-image-2.5-sunburst по 16 ₽, их -edit-варианты по 22 ₽. Обе дешевле gpt-image-2 (19/22 ₽) и сильнее по русскому тексту; редактирование меняет только названное, не разрушая лица, фон и надписи. Новое в параметрах: background (transparent — прозрачный PNG для макетов и мерча) и output_format (png|jpeg|webp). ⚠️ Пропорции у семейства: auto, 1:1, 16:9, 9:16, 4:5, 3:2, 4:3, 3:4, 5:4, 2:3, 21:9 (уточнено 09-09-26: в день релиза здесь было сказано «только три размера» — ограничение оказалось нашим, а не модельным). По умолчанию auto: с image_input кадр остаётся как у присланного фото, без него его подбирает модель. Flare и Sunburst стоят одинаково: Flare отвечает быстрее (около 18 с), Sunburst дольше (около 30 с), но точнее держит серию правок. Если передать image_input в обычный слаг, запрос сам уйдёт в редактирование — референсы не теряются.
• 2026-09-07 — Цены озвучки на этой странице исправлены. el-tts-turbo — 8 ₽ за каждую начатую 1000 знаков (страница писала 6 ₽ и «2500 знаков = 18 ₽», реально 24 ₽); el-tts-multilingual-v2 и el-dialogue-v3 — 18 ₽ за начатую 1000 знаков (страница показывала флэт 39 ₽ и 49 ₽, а 5000 знаков стоят 90 ₽). Флэт-числа остаются только фолбэком, когда длина текста неизвестна. Каждая цифра сверена бесплатной сметой POST /generate/estimate.
• 2026-09-07 — Перечень моделей стал производным от контракта. Раздел «Каталог моделей и цен» собирает php artisan agent:docs-sync из того же источника, что отдаёт GET /capabilities, и им же проверяется (--check). До этого страница называла 49 моделей из 63: не хватало grok-image-2 (3 ₽ — вшестеро дешевле соседей), gpt-5.6-luna (60/360 ₽ за 1M токенов), gpt-5.6-terra, gpt-image-2, seedream-5-lite[-edit], seedream-5-pro-layers, grok-image[-2-edit] и всего семейства nano-banana-pro-1k|4k / nano-banana-2-1k|2k|4k.
• 2026-08-06 — Qwen Image 3.0: четыре новые модели изображений Alibaba — qwen-image-3 (7 ₽) и qwen-image-3-edit (7 ₽), старшие qwen-image-3-pro (14 ₽) и qwen-image-3-pro-edit (14 ₽). Разрешение 2K стоит столько же, сколько 1K — берите 2K. Сильны в ровном тексте на картинке (вывески, ценники, упаковка). Параметры: resolution (1K|2K), output_format (png|jpeg), negative_prompt (до 5000), seed (0..2147483647), prompt_extend. ⚠️ prompt ≤ 800 символов — длиннее отклоняется до списания. Режим редактирования принимает 1–10 картинок в image_input. См. примеры.
• 2026-08-03 — PixVerse V6: новая видеомодель pixverse-v6 — самый дешёвый посекундный тариф каталога, от 4 ₽/сек, звук в комплекте, 3–15 с, до 1080p. Пять режимов через pv_mode: text (по описанию), image (оживление одного фото), transition (переход между first_frame_image_url и last_frame_image_url), reference (сцена по 1–7 фото с именами @Image1…@Image7) и extend (продление своего готового ролика по video_url или parent_task_id). Тариф — пара «разрешение + звук»: 360p 4/6 ₽/сек, 1080p 15/19 ₽/сек. См. раздел «PixVerse V6».
• 2026-08-02 — MiniMax H3: новая видеомодель minimax-h3 (Hailuo 03) — 2K со встроенным стереозвуком, 4–15 с, 37 ₽/сек. Три режима в одной модели через h3_mode: text (по описанию), image (опорные кадры) и reference (мультимодальные референсы: до 9 изображений + до 3 видео + до 3 аудио одним запросом). ⚠️ Провайдер тарифицирует длительность входного видео наравне с результатом, а изображения сверх пятых — по 11 ₽; видео-референс принимается ТОЛЬКО загруженный через POST /upload-media (длительность чужой ссылки измерить нельзя, такой запрос отклоняется до списания). См. раздел «MiniMax H3».
• 2026-07-19 — Gemini TTS: две новые голосовые модели Google — gemini-flash-tts (Gemini 3.1 Flash TTS, ПОСИМВОЛЬНО 13₽/1000 знаков) и gemini-pro-tts (Gemini 2.5 Pro TTS, 18₽/1000 знаков): одиночная озвучка И диалоги (1–2 голоса), 30 фирменных голосов Google, эмоции inline-тегами [радостно]…[шёпотом], стили Deadpan/Whisper/Newscaster, temperature; лимит 5000 знаков → больше авто «длинная озвучка» (см. раздел «Gemini TTS»).
• 2026-07-16 — Озвучка стала посимвольной: el-tts-turbo тарифицируется за каждую начатую 1000 знаков (флэт 29 ₽ отменён; действующая ставка — 8 ₽, см. запись от 2026-09-07); одиночный запрос — до 5000 знаков; длинная озвучка: prompt от 5001 до 200 000 знаков автоматически нарезается на куски ~4800, озвучивается и склеивается в один mp3 — /generate вернёт voiceover_id + status_url (GET /voiceover/long/{id}) вместо generation_id.
• 2026-07-14 — SeeDream 5 Pro: seedream-5-pro (text-to-image) и seedream-5-pro-edit (image-to-image, до 10 референсов) — фотореализм до 2K, точный текст на изображении; параметры quality (basic=1K / high=2K) и output_format (png/jpeg).
• дата не записана — Новые модели: seedance-2-mini (бюджетный Seedance, посекундно, все функции) и nano-banana-2-lite (Gemini 3.1 Flash Lite Image — txt2img + img2img по референсу).
• дата не записана — Grok Imagine 1.5: теперь ОБА grok-ttv и grok-itv на движке grok-imagine-video-1-5-preview: duration 1–15 сек, без mode (контент-фильтр включён).
• дата не записана — «Оживить и Озвучить»: omnihuman-1-5, volcengine-lipsync, omnihuman-1-5/human-identification — посекундная оплата.

Полный список моделей и параметров всегда в GET /capabilities, точная цена запроса — в бесплатном POST /generate/estimate.