Сценарии REST API и MCP

REST API и MCP-сервер запускают те же задачи, что и приложение VlogMe, — Director, Video, Image и Audio Studio, Aisma, DUB и Новостные видео — в том же аккаунте, с тем же балансом кредитов и тем же Lab.

Как получить доступ. API и MCP доступны всем зарегистрированным пользователям VlogMe. Создайте ключ в Account → API & MCP; разрешение поддержки не требуется. По вопросам больших объёмов и интеграции для команды пишите на sales@vlogme.ai.

Дальше интеграция проходит пять шагов:

1. Создайте ключ API в разделе Account → API & MCP (кабинет пока доступен только на английском).
2. Загрузите фото, видео или аудио, нужные задаче, или возьмите файл из Lab.
3. Запросите цену: VlogMe вернёт точную стоимость задачи в кредитах.
4. Запустите задачу с этой ценой. По другой цене она не запустится.
5. Отслеживайте её запросами или через вебхук; результаты сохраняются в Lab.

То же самое агенты могут делать через MCP-сервер: его инструменты охватывают задачи, Director, файлы Lab, проекты, шаблоны, голоса, Новостные видео и публикации в соцсетях — с тем же ключом, балансом и проверками, что и REST.

Об изменениях API и MCP мы сообщаем в журнале разработки.

ИИ-агенты работают в том же аккаунте, с тем же ключом, балансом и ценами через MCP-сервер https://vlogme.ai/mcp. Точные шаги для каждого клиента — на странице настройки MCP-сервера:

• Claude Code, Cursor и VS Code
• Gemini CLI и Codex
• сценарии n8n

В Claude Code это одна команда, ключ — в VLOGME_API_KEY:

claude mcp add --transport http vlogme https://vlogme.ai/mcp --header "Authorization: Bearer $VLOGME_API_KEY"

Перед любой платной задачей агент запрашивает цену и показывает вам кредиты. Раздел MCP-сервер ниже перечисляет все инструменты и права ключа, которые им нужны.

Каждый запрос передаёт ключ в заголовке Authorization:

Authorization: Bearer vma_…

• Ключ может то, что вы отметили при его создании в Account → API & MCP:
  • read — показывать файлы Lab, задачи и баланс и запрашивать цену. Это право есть у каждого ключа.
  • write — загружать и импортировать файлы, переименовывать и архивировать их, сохранять проекты, планировать и готовить материалы в Director и запускать платные задачи по рассчитанной цене.
  • delete — удалять файлы, проекты, клоны голоса и мониторы новостей. Удаление нельзя отменить.
  • share — создавать и отзывать публичные ссылки.
  • publish — публиковать видео или ставить их в расписание в подключённых соцсетях.
• Ключи, созданные до появления этого выбора, сохраняют прежние права: ключ «Read» только читает, а ключ «Read and create jobs», как и раньше, также удаляет файлы и создаёт ссылки.
• Запрос, недоступный ключу, отклоняется с 403 и code: scope_missing. GET /api/me показывает права самого ключа в token.scopes.
• Ключ действует от 1 до 365 дней (по умолчанию 90). Отозвать его можно в любой момент в Account → API & MCP — интеграции, которые им пользуются, сразу остановятся.
• Ключом нельзя сменить тариф, создать другие ключи, удалить аккаунт или открыть инструменты администратора: для этого нужен вход в аккаунт (code: session_required).

Храните ключи в секрете: они действуют от имени вашего аккаунта и расходуют его кредиты (Условия использования).

Два публичных адреса описывают всё, что может отправить интеграция. Ключ для них не нужен.

• GET /api/catalog перечисляет все kind задач (с workflow или моделью): входные данные в виде JSON Schema, нужные файлы Lab, допустимые длительности, соотношения сторон и качество, правило цены, пример входных данных с его ценой в кредитах и доступность прямо сейчас. ?kind=video сужает список. Там же — схемы Director: новый проект, команда правки, реплика в чате и подготовка материалов.
• GET /api/openapi.json — описание REST API в формате OpenAPI 3.1. Поле x-scope у каждой операции называет нужное право ключа.

Поля из списка server_fills, например длительность видео, VlogMe измеряет по вашему файлу, поэтому их можно не передавать.

Задача — это одна единица работы: клип, аватар, изображение, голосовая дорожка, правка, дубляж, изменение в Aisma, видео Новостные видео или рендер Director. Её kind — одно из значений video, avatar, image, audio, video_edit, dub, trend, aisma, voice_clone, director, а input содержит те же настройки, что и соответствующий экран приложения.

Обычные изменения в Image Editor экспортируются в браузере и не являются серверной задачей. Для генерации и редактирования изображений с ИИ используйте kind: image с нужным workflow.

Например, запросить цену изображения и запустить задачу:

curl https://vlogme.ai/api/jobs/quote \
  -H "Authorization: Bearer $VLOGME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "image", "input": {…}}'

curl https://vlogme.ai/api/jobs \
  -H "Authorization: Bearer $VLOGME_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b8e-7d4a-4f0e-9b1a-2c3d4e5f6a7b" \
  -d '{"kind": "image", "input": {…}, "quoted_credits": 12, "quote_fingerprint": "…"}'

Если цена или входные данные изменились после расчёта, запуск отклоняется с кодом 409 и ничего не списывается: запросите цену заново. Если задача завершилась ошибкой, подлежащие возврату кредиты автоматически возвращаются на баланс. Запущенную задачу нельзя отменить: провайдеры не всегда могут её остановить.

Изменить один клип правки Aisma. В готовой правке Aisma можно заново сгенерировать один клип, не переделывая всё видео. GET /api/jobs/{id}/clips, где id — задача самой правки, возвращает её клипы с номером index и ценой повторной генерации в credits. Запросите цену и запустите задачу aisma с input вида {"clip": {"job_id": "<id задачи правки>", "op": "regenerate", "part": <index>, "clarification": "…"}}: уточнение необязательно, а клип создаётся на той же версии и в том же качестве, что и правка. Списывается только цена этого клипа, и ничего не списывается, если Aisma не применила уточнение, не смогла создать клип или оставила его как в исходном видео. В input.clip_result завершённой задачи указаны итог outcome и, если уточнение не применено, причина reason; её результат — обновлённое полное видео, новый файл в Lab. Для правки, у которой нет клипов для чтения, clips равно null: она создана до того, как клипы стало можно менять, или её файлы удалены вместе с исходным видео. В остальных случаях disabled говорит, почему сейчас нельзя изменить ни один клип (starting, failed, busy или materials; null, если можно), а finish — как привести полное видео в актуальное состояние (assemble: запустите задачу с {"clip": {"job_id": "…", "op": "assemble"}}; reassemble: POST /api/jobs/{id}/reassemble; null: видео актуально). Клип с mode, равным change, Aisma оставила как в исходном видео: чтобы сгенерировать его заново с ключом, нужно передать уточнение. Обновления, которые завершились без списания, ограничены: есть почасовой лимит для каждой правки и общий — для всех правок аккаунта. Когда любой из них исчерпан, расчёт цены и запуск задачи отвечают 429 с retry_after_s. Уточняющие вопросы Aisma задаёт только в приложении: правку, запущенную с ключом, она ни о чём не спрашивает.

Ключ с правом write может провести видео от идеи до готового файла:

1. POST /api/director/projects с {"version": 2, "concept": "…"} создаёт проект.
2. POST /api/director/projects/{id}/turns с новым client_request_id и base_revision проекта просит Director составить план. GET /api/director/turns/{id реплики}?wait=30 ждёт, пока план будет готов или Director задаст вопрос; ответить на него можно через POST /api/director/turns/{id реплики}/answer.
3. POST /api/director/projects/{id}/prepare бесплатно готовит изображения, голоса и музыку, а GET /api/director/projects/{id}/view показывает, что уже готово. Подготовка занимает время: запрашивайте /view снова, пока все materials не станут ready.
4. POST /api/director/projects/{id}/render/quote рассчитывает цену видео (remake_scene_numbers заново делает выбранные сцены), а POST /api/director/projects/{id}/render с этими revision, quoted_credits, quote_fingerprint и Idempotency-Key запускает его. Если после расчёта план изменился, запуск отклоняется с 409 (code: revision_conflict) и ничего не списывается.
5. GET /api/jobs/{id задачи}?wait=30 — до окончания задачи; затем GET /api/director/projects/{id}/result возвращает видео и субтитры со ссылками, действующими 15 минут.

Планирование, чат и бесплатная подготовка через ключ расходуют тот же бесплатный лимит аккаунта, что и приложение: агент, который много планирует, исчерпывает его и для приложения. Когда лимит на время исчерпан, ответ содержит limited: true.

Лица и места бесплатны в пределах лимита. После него изображения бесплатного аккаунта не создаются: ответ /prepare перечисляет их в поле plan_required (и в skipped), и чтобы создавать изображения дальше, нужен тариф. С тарифом изображения сверх его лимита возвращаются в поле charged с ценой: оцените их через POST /api/jobs/quote (kind director, input {"v": 2, "stage": "materials", "project_id": "…", "revision": 3, "keys": ["…"]}) и запустите как любое платное задание. Изображение, которое к рендеру видео всё ещё missing в /view, создаётся в рендере и входит в его показанную цену. Новый вариант уже готового изображения («Попробовать снова») — это POST /api/director/projects/{id}/prepare с его ключом в keys и "regenerate": true.

Чтобы изменить план, отправьте сообщение в /turns (с scope.block_ids, чтобы изменить только некоторые сцены) или структурную правку в POST /api/director/projects/{id}/edits по схеме director.edit_command_schema из GET /api/catalog. POST /api/director/projects/{id}/undo возвращает прежнюю версию. Каждое изменение передаёт прочитанный base_revision и новый client_request_id: устаревшая версия отклоняется с 409, а повтор того же client_request_id воспроизводит изменение, а не делает его дважды.

Файлам, которые вы добавляете в план, нужен rights_confirmed: true. Переданный через ключ, он означает ваше собственное подтверждение, что у вас есть права на эти файлы и на людей в них (Условия использования).

• GET /api/assets показывает файлы Lab, начиная с новых. section=main — «Файлы» (готовые видео, результаты и загрузки), working — файлы, которые проект использует в работе, archived — архив, all (по умолчанию) — все файлы, кроме архивных. Фильтры kind, project_id (или none) и q; fields=compact не возвращает метаданные; страницы — через limit и полученный next_offset. GET /api/assets/working-projects группирует рабочие файлы по проектам.
• POST /api/assets/intent с полями mime_type, bytes и title резервирует файл в Lab и возвращает адрес и токен для возобновляемой загрузки (tus). Изображения: JPEG, PNG, WebP, BMP. Видео: MP4, MOV, M4V, до 150 минут. Аудио: MP3, M4A, WAV, OGG. До 1 ГБ на файл.
• Если добавить content_sha256 (SHA-256 файла: 64 шестнадцатеричных символа в нижнем регистре), уже загруженный вами такой же файл используется повторно: ответ 200 содержит reused: true и этот файл, загружать ничего не нужно. Чтобы сохранить вторую копию, передайте ещё и allow_duplicate: true.
• POST /api/assets/{id}/complete проверяет загрузку, после чего файл можно указать во input задачи.
• Для ключа API ответ также содержит put_url — один подписанный адрес, куда весь файл загружается одним PUT (curl -T clip.mp4 -H "Content-Type: video/mp4" "$put_url") вместо tus. Заголовок Idempotency-Key (UUID) при повторе возвращает тот же файл.
• POST /api/assets/import с {"url": "https://…"} и Idempotency-Key в фоне загружает файл с публичного HTTPS-адреса. Ответ — 202 с id нового файла; затем GET /api/assets/{id} показывает import.status, пока файл не будет готов, или failed с error_code. Адреса самого VlogMe, частных сетей и IP-адреса отклоняются.
• PATCH /api/assets/{id} с title переименовывает файл, а с archived: true переносит его в архив (false возвращает); файлы, которые проект использует в работе, остаются в рабочих файлах.
• DELETE /api/assets/{id} удаляет файл навсегда (право delete). Файл, который ещё нужен запущенной задаче, не удаляется: ответ 409.
• GET /api/assets/working-projects/{id}/cleanup показывает, что удалит очистка в одном проекте (прежние варианты, неиспользованные изображения, остатки), с причиной для каждого файла. POST по тому же адресу с asset_ids из этого списка удаляет до пяти из них за запрос (право delete). Автоматически ничего не удаляется.
• GET /api/assets/{id}/download возвращает закрытую ссылку на 60 секунд; ttl продлевает её до часа, а redirect=1 отвечает переадресацией на файл, так что его скачивает curl -L.

Файлы, загруженные через API, остаются закрытыми в вашем Lab — так же, как файлы, загруженные в приложении.

• GET /api/projects показывает ваши проекты, начиная с новых: проекты Director (с идеей и кратким описанием) и черновики Новостные видео, Aisma, DUB и Image Editor (с сохранёнными данными). Фильтр kind; страницы — через limit и полученный next_cursor.
• POST /api/projects с kind, title и data сохраняет новый черновик; заголовок Idempotency-Key при повторе возвращает тот же черновик. PUT /api/projects/{id} с текущей revision черновика сохраняет изменения, а устаревшая версия отклоняется с 409. DELETE /api/projects/{id} удаляет проект (право delete); его файлы в Lab остаются.
• Проекты Director создаются через POST /api/director/projects (см. выше), а не как черновики.
• GET /api/templates показывает опубликованные шаблоны Aisma (category, q, limit, cursor), GET /api/templates/{id} — один шаблон, а POST /api/templates/{id}/open с Idempotency-Key открывает его как новый проект.
• GET /api/voices показывает голоса, доступные задачам и персонажам Director: готовые голоса и ваши готовые клоны. GET /api/voice-clones показывает ваши клоны со статусом, а DELETE /api/voice-clones/{id} удаляет клон, в том числе у провайдера голосов (право delete).

• GET /api/trends/search?q=… ищет свежие новости (language — en или ru; country, category, domains, sort_by). POST /api/trends/script пишет сценарий по новости с опорой на её источники, а POST /api/trends/verify сверяет сценарий с ними.
• Мониторы новостей ищут новые сюжеты по расписанию: GET и POST /api/trends/monitors, PUT и DELETE /api/trends/monitors/{id}.
• GET /api/social/connections показывает подключённые соцсети, а GET /api/social/publications — ваши публикации со статусом. Подключить аккаунт можно только после входа в приложении.
• POST /api/social/publications с asset_id (готовое видео) и platform, по желанию с caption, headline, visibility, cover_asset_id и scheduled_at, а также с Idempotency-Key публикует видео или ставит его в расписание. Для этого нужно право publish, которое есть у ключа, только если вы его отметили. Публикацию видят все: агент должен показать вам видео, площадку и подпись и публиковать только после вашего явного согласия.
• POST /api/social/publications/{id}/cancel отменяет публикацию, которая ещё не вышла (право publish или write).
• Предпросмотр видеоредактора (POST /api/video-editor/preview) возвращает поток MP4, поэтому он доступен только через REST.

Узнать, что работа закончена, можно двумя способами.

Долгий опрос. GET /api/jobs/{id}?wait=30 и GET /api/director/turns/{id}?wait=30 ждут до указанного числа секунд (от 0 до 30), пока задача или реплика не завершится (реплика останавливается и тогда, когда Director задаёт вопрос), и возвращают её с waited_seconds. Пока работа идёт, retry_after_s подсказывает, когда спросить снова. Так ждёт агент на ноутбуке, который не может принимать вебхуки.

Вебхуки. Укажите webhook_url — публичный HTTPS-адрес — при запуске задачи с ключом API, и VlogMe отправит событие, когда задача завершится:

{"id": "job.<job id>.succeeded", "type": "job.succeeded", "created_at": "…",
 "job": {"id": "…", "kind": "image", "status": "succeeded", "result_asset_id": "…", "error_code": null}}

• Тип события — job.succeeded, job.failed или job.partial (часть результатов уже в Lab, а кредиты за недостающие части возвращены). Задача на проверке (needs_review) ещё не завершена: событие придёт, когда она завершится.
• Частично готовую задачу, у которой не удалась финальная сборка, можно бесплатно собрать заново запросом POST /api/jobs/{id}/reassemble. Когда сборка закончится, новое событие сообщит результат — даже если сборка снова не удалась и задача осталась частично готовой. У каждого результата свой id события: у частичного в конце стоит его error_code (job.<job id>.partial.<error code>), а после неудачных повторных сборок — ещё .retry<n>, где n — их число; GET /api/jobs/{id} показывает это число в поле reassembly_failures. Правка Aisma, клипы которой менялись, собирается иначе: для неё этот запрос отклоняется с кодом 409 (clip_job_required), а видео бесплатно собирает задача с input вида {"clip": {"job_id": "<id задачи правки>", "op": "assemble"}}. Такая же задача собирает видео, если задача клипа завершилась частично с кодом aisma_clip_video_pending.
• Каждая доставка содержит заголовки X-VlogMe-Event-Id, X-VlogMe-Timestamp и X-VlogMe-Signature: v1=<hex> — HMAC-SHA256 от <timestamp>.<body>, где ключом служит SHA-256-хеш вашего ключа API. Проверяйте подпись и отклоняйте устаревшие метки времени.
• Если доставка не получила ответ 2xx, она повторяется до восьми раз — сначала через 30 секунд, затем реже, до раза в час. Отзыв ключа прекращает доставки.

ИИ-агенты, поддерживающие Model Context Protocol, подключаются к https://vlogme.ai/mcp (JSON-RPC 2.0 через HTTP POST) с тем же ключом Authorization: Bearer; https://vlogme.ai/api/mcp — тот же сервер по второму адресу. Поддерживаемые версии протокола: 2026-07-28 (без состояния, с заголовками Mcp-Method и Mcp-Name и методом server/discover), а также 2025-11-25, 2025-06-18 и 2025-03-26 (с initialize, который отвечает той версией, что запросил клиент). Запрос без заголовка MCP-Protocol-Version считается запросом версии 2025-03-26. Размер запроса — до 1 МБ.

Инструменты охватывают то, что ключ может делать через REST. Каждому инструменту нужно право из таблицы. Список инструментов не зависит от прав ключа; вызов, недоступный ключу, возвращается как отказ с code: scope_missing. С ?tools=all в адресе (https://vlogme.ai/mcp?tools=all) список называет все инструменты из таблицы; как подключить каждый клиент, показано на странице настройки MCP-сервера.

• Инструменты, которые только читают, помечены readOnlyHint. Инструменты, которые удаляют, помечены destructiveHint, и их описание начинается с «Irreversible.»; описание инструмента, который делает что-то публичным, начинается с «Public.», а платные инструменты предупреждают о списании кредитов. Агент должен сначала подтвердить такие вызовы у вас.
• Аргументы проверяются по схеме инструмента. Неверный или лишний аргумент отклоняется до отправки запроса — результатом с isError: true и code: invalid_input.
• Каждый инструмент-список принимает limit (от 1 до 50, по умолчанию 20) и cursor и возвращает next_cursor (null на последней странице).
• vlogme_wait_job и vlogme_director_turn ждут до 30 секунд за вызов; вызывайте их снова, пока в ответе есть retry_after_s.
• Ресурсы: resources/read отдаёт vlogme://docs/agents (руководство для агентов: от идеи до видео, правила оплаты, ожидание и ошибки), vlogme://catalog (каталог задач) и vlogme://openapi (описание OpenAPI). initialize возвращает краткие инструкции с теми же сценариями.

Чтобы запустить задачу через MCP:

1. Вызовите vlogme_quote_job с kind и input и проверьте возвращённую стоимость credits.
2. Вызовите vlogme_create_job с теми же kind и input, новым UUID idempotency_key, значением quoted_credits из полученного credits и неизменённым quote_fingerprint. Для Aisma также передайте неизменённый quote_proof из расчёта цены.
3. Если подтверждение истекло или цена либо входные данные изменились, запросите и подтвердите новую цену перед повторной попыткой. Повтор уже принятого запроса с тем же idempotency_key возвращает ту же задачу.

Видео Director запускается по тому же правилу: vlogme_director_quote_render, показать цену, затем vlogme_director_render с этой ценой и idempotency_key.

Необязательный webhook_url получает события задачи, описанные выше. MCP использует тот же ключ API, баланс и проверки цены, что и REST.

Для Codex добавьте сервер в ~/.codex/config.toml, а ключ храните в переменной окружения VLOGME_API_KEY:

[mcp_servers.vlogme]
url = "https://vlogme.ai/mcp"
bearer_token_env_var = "VLOGME_API_KEY"
tool_timeout_sec = 120

• Задачи стоят столько же кредитов, сколько в приложении, и списываются с того же баланса; рассчитанная цена и есть цена.
• Idempotency-Key — это UUID. Повторное использование ключа для другого запроса отклоняется.
• Задачам Aisma нужен quote_proof, который возвращает расчёт цены. У него есть срок действия: когда он истечёт, запросите цену снова.
• Задача Aisma принимает необязательное поле engine: v1 или v2; если его не передать, используется v2. Версии различаются ценой и числом фотореференсов; лимит каждой указан в GET /api/catalog?kind=aisma. Расчёт цены действует для одной версии: чтобы запустить другую, запросите цену снова. Проект, открытый из шаблона, всегда выполняется на v2.
• Ошибки возвращаются в JSON {"error": "…", "code": "…"} с HTTP-статусом: 400 — неверные данные (invalid_input), 403 — запрос, который не разрешают права ключа (scope_missing, session_required), 404 — не найдено, 409 — изменились цена, входные данные или план, 429 — слишком много запросов, 503 — сервис или провайдер временно недоступен.
• Число запросов ограничено. Сверх лимита ответ — 429 с code: rate_limited и заголовком Retry-After: подождите указанное число секунд и повторите.
• Через MCP отклонённый вызов инструмента — не HTTP-ошибка: он возвращается как результат инструмента с isError: true, внутри которого тот же JSON (error, status и, если есть, code). HTTP-ошибками там остаются только отсутствующий или неверный ключ (401), аккаунт без доступа к API или чужой Origin (403) и некорректный запрос.
• На работу, созданную через API, распространяются Условия использования, как и на работу в приложении.