/brandsСписок брендов
Параметры запроса:
- limit integer
- cursor string
Подключайте MAA Studio к своим сервисам: сценарии, ролики с цифровым двойником, карусели и публикации через REST API, вебхуки и MCP.
REST API на JSON проходит весь путь без кабинета: идея, сценарий, ролик с лицом, слайд-шоу или мультфильм, сериал с героем, перевод, нарезка клипов, карусели и публикация в соцсети. У каждого платного запуска есть метод, который заранее говорит цену, ту же, что показывает кабинет. О готовности мы сообщаем вебхуком, поэтому опрашивать API постоянно не нужно.
Каждый запрос подписывается ключом вида maa_live_… в заголовке Authorization: Bearer. Ключ принадлежит одному пространству и видит только его данные. Полностью ключ показывается один раз при создании, дальше в кабинете виден только его префикс. Храните ключ на сервере: в мобильном приложении, браузере и публичном репозитории ему не место.
Authorization: Bearer maa_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXКлючу выдаются только нужные разрешения. Запрос к методу, на который у ключа нет разрешения, вернёт 403 insufficient_scope.
| Разрешение | Название | Что даёт | Ролики |
|---|---|---|---|
content:read | Чтение контента | Бренды, идеи, сценарии, ролики, баланс и цены перед запуском | нет |
content:write | Запись контента | Идеи и сценарии, остановка сценария | нет |
videos:create | Создание роликов | Ролик с лицом, слайд-шоу, мультфильм, одобрение черновика и отмена. Запуск списывает ролики с баланса | списывает |
publish | Публикации | Аккаунты, планирование, отмена и список публикаций | нет |
analytics:read | Аналитика | Чтение аналитики брендов | нет |
clips | Нарезка клипов | Проекты нарезки из длинного видео (списывает ролики) | списывает |
carousels | Карусели и посты | Создание и чтение каруселей и постов (одно текстовое действие за штуку) | нет |
avatars:read | Двойники и голоса | Состояние видео-двойника и голосов. Создать двойника или голос можно только в кабинете | нет |
translations | Перевод роликов | Перевод готового ролика на другие языки (списывает ролики) | списывает |
series | Контент-планы и сериалы | Контент-план и сериал с героем, сценарии по плану (текстовые действия) | нет |
billing:read | Тариф и расход | Тариф, что он разрешает, расход и цена докупки. Оплата только на странице оплаты | нет |
Отозванный ключ перестаёт работать сразу (401 invalid_api_key). Если тариф пространства перестал включать API, методы отвечают 402 plan_required.
Запросы и ответы в JSON (Content-Type: application/json), время в ISO 8601 (UTC), идентификаторы это UUID. Точный адрес вашего API-хоста показан в кабинете, в разделе «API и вебхуки».
Лимит считается отдельно для каждого ключа, окном в одну минуту.
| Тариф | Запросов в минуту | Платных запусков в минуту |
|---|---|---|
| «Эксперт» | 120 | 10 |
| «Агентство» | 600 | 30 |
Платные запуски (в справочнике они помечены «списывает») считаются по отдельному, более строгому лимиту. Каждый ответ содержит заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset (unix-время сброса). При превышении приходит 429 с заголовком Retry-After в секундах: подождите столько и повторите запрос.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790000040
Retry-After: 17
Content-Type: application/json
{ "error": { "code": "rate_limited", "message": "Too many requests" } }Любая ошибка приходит с подходящим HTTP-статусом и телом { "error": { "code", "message" } }. Ориентируйтесь на code: он стабилен, а message написан для людей и может меняться.
{
"error": {
"code": "insufficient_scope",
"message": "This key has no access to videos:create"
}
}| code | HTTP | Когда |
|---|---|---|
invalid_api_key | 401 | Ключ не передан, неверен или отозван. |
plan_required | 402 | Тариф пространства не включает API. |
insufficient_scope | 403 | У ключа нет нужного разрешения. |
forbidden | 403 | Нет доступа к этому ресурсу. |
not_found | 404 | Ресурса нет или он принадлежит другому пространству. |
validation_error | 400 | Запрос не прошёл проверку: смотрите message и details. |
rate_limited | 429 | Слишком много запросов, смотрите Retry-After. |
insufficient_balance | 402 | На балансе не хватает роликов или действий. Ничего не списано. |
idempotency_conflict | 409 | Этот Idempotency-Key уже использован с другим запросом. |
idempotency_in_progress | 409 | Первый запрос с этим ключом ещё выполняется, повторите чуть позже. |
quote_invalid | 400 | Quote-Id не принадлежит этому пространству. Запросите цену заново. Ничего не списано. |
quote_expired | 409 | Цена запрошена больше 15 минут назад. Запросите её заново. Ничего не списано. |
quote_mismatch | 409 | Цена была запрошена для другой операции или других параметров. Запросите цену именно этого запроса. Ничего не списано. |
quote_price_changed | 409 | Цена изменилась с момента запроса. Запросите её заново. Ничего не списано. |
internal_error | 500 | Ошибка на нашей стороне. Повторите запрос; если не помогло, напишите в поддержку. |
provider_unavailable | 503 | Сервис, от которого мы зависим, временно недоступен. Повторите позже. |
video.qc_failed | 422 | Ролик не прошёл автоматическую проверку, и мы его не отдали. Ролики вернулись на баланс. |
content_rejected | 422 | Содержимое не прошло модерацию. |
story.plan_required | 402 | Мультфильмы не входят в тариф пространства. Ничего не списано. |
series.hero_plan_required | 402 | Сериал с героем не входит в тариф пространства. Ничего не списано. |
series.episodes_limit | 402 | На этом тарифе в сериале меньше серий. Ничего не списано. |
realism.twin_required | 409 | Для этого уровня нужен видео-двойник бренда. Запишите его в кабинете. Ничего не списано. |
realism.twin_not_ready | 409 | Видео-двойник ещё не готов: идёт подготовка или ждём согласия. Ничего не списано. |
realism.photo_required | 400 | Видео-двойник работает только на уровнях premium и max. Для standard выберите аватар по фото. Ничего не списано. |
realism.engine_unavailable | 409 | Этот уровень недоступен для этого видео-двойника. Выберите другой. Ничего не списано. |
realism.level_not_connected | 409 | Этот уровень для аватара по фото пока не подключён. Выберите standard. Ничего не списано. |
avatar.not_talking | 400 | Этот образ в полный рост, он не говорит. Выберите аватар, у которого canTalk равно true. Ничего не списано. |
studio.unavailable | 503 | Этот вид ролика пока не подключён. Ничего не списано. |
story.too_long | 400 | Сценарий не подходит к этому формату по длине. Сократите его или выберите другой формат. Ничего не списано. |
story.unsafe | 400 | В истории есть то, что мы не снимаем: сбор денег, вред себе или откровенные сцены. Ничего не списано. |
story.wrong_phase | 409 | Черновик не ждёт одобрения: он уже одобрен, отменён или ещё готовится. |
story.busy | 409 | Сейчас перерисовывается кадр или герой. Одобрите через минуту. |
series.hero_not_synthetic | 400 | Героем сериала или мультфильма может быть только ИИ-персонаж, а не двойник человека. Ничего не списано. |
series.wrong_state | 409 | Сериал сейчас пересобирается. Повторите через минуту. |
action.wrong_state | 409 | Статус уже изменился: останавливать или отменять нечего. Прочитайте ресурс ещё раз. |
delete.scheduled | 409 | На это назначены публикации. Сначала отмените их. |
delete.in_progress | 409 | Это ещё делается. Сначала остановите. |
clips.platform_unsupported | 400 | Ссылки на страницы видеоплощадок и соцсетей скачать нельзя. Нужна прямая ссылка на файл. |
clips.url_invalid | 400 | Ссылка не похожа на публичный адрес http или https. |
clips.url_unreachable | 400 | Файл по ссылке не скачался. |
clips.not_media | 400 | По ссылке не видео со звуком. |
clips.too_long | 400 | Видео длиннее, чем мы принимаем. |
clips.too_large | 400 | Файл больше, чем мы принимаем. |
Списки принимают limit (от 1 до 100, по умолчанию 20) и cursor. Ответ приходит в виде { "data": [...], "nextCursor": "..." }. Пока nextCursor не равен null, передавайте его как cursor и получайте следующую страницу. Значение курсора непрозрачное: не разбирайте и не собирайте его сами.
GET /videos?limit=2&status=ready
{
"data": [{ "id": "…", "status": "ready", "title": "…" }, { "id": "…", "status": "ready", "title": "…" }],
"nextCursor": "eyJ0IjoiMjAyNi0xMC0xMlQwOTozMDowMFoifQ"
}
GET /videos?limit=2&status=ready&cursor=eyJ0IjoiMjAyNi0xMC0xMlQwOTozMDowMFoifQЕсли запрос оборвался по сети, непонятно, дошёл он или нет, а повтор может создать второй ролик и списать баланс ещё раз. Поэтому в каждый POST добавляйте заголовок Idempotency-Key: любая строка длиной от 1 до 200 печатных ASCII-символов, удобнее всего UUID. Мы храним результат 24 часа. Повтор с тем же ключом и тем же телом вернёт сохранённый ответ с заголовком Idempotent-Replayed: true и ничего не создаст заново.
curl -i -X POST /videos \
-H "Authorization: Bearer $MAA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f5d1c0e-7b2a-4c11-9a4e-0d6f2b8c9e10" \
-d '{"scriptId":"…"}'
# A repeat with the same key and the same body returns the stored answer
# and the header Idempotent-Replayed: true (no second charge).409 idempotency_conflict: ключ уже использован с другим телом запроса. Для нового запроса нужен новый ключ.409 idempotency_in_progress: первый запрос ещё выполняется. Повторите через пару секунд с тем же ключом.У каждого платного запуска есть парный метод, который ничего не запускает и ничего не удерживает, а только отвечает: сколько спишется (credits, в роликах или в текстовых действиях), сколько на балансе (available), можно ли начать сейчас (canStart) и, если нельзя, каким кодом ответит запуск (blockedBy). Цена считается той же функцией, что и в кабинете, и запуск удерживает ровно её.
В ответе есть quoteId. Передайте его в заголовке Quote-Id при запуске, и запуск пройдёт только если цена всё ещё та же, запрос тот же, пространство то же и с момента ответа прошло не больше 15 минут. Иначе придёт отказ, и ничего не спишется. Заголовок необязателен для вашего кода, но MCP-сервер передаёт его всегда: так ассистент не может потратить больше, чем показал человеку.
| Запуск | Что списывает | Цена заранее |
|---|---|---|
POST /videos | ролики | /scripts/{scriptId}/video-quote |
POST /videos/faceless | ролики | /scripts/{scriptId}/faceless-quote |
POST /videos/{videoId}/story/approve | ролики | /videos/{videoId}/approval-quote |
POST /videos/{videoId}/translations | ролики | /videos/{videoId}/translation-quote |
POST /brands/{brandId}/carousels | текстовые действия | /brands/{brandId}/carousels/quote |
POST /brands/{brandId}/clip-projects | ролики | /brands/{brandId}/clip-projects/quote |
POST /brands/{brandId}/series | текстовые действия | /brands/{brandId}/series/quote |
POST /series/{seriesId}/scripts | текстовые действия | /series/{seriesId}/scripts/quote |
# 1. Ask what it will cost. Nothing is started and nothing is held
curl -s "$BASE/scripts/$SCRIPT_ID/faceless-quote?kind=slideshow" -H "$AUTH"
{
"quoteId": "qt_eyJ3cyI6Ii4uLiJ9.c2lnbmF0dXJl",
"operation": "createFacelessVideo",
"unit": "video",
"credits": 0.5,
"available": 12,
"sufficient": true,
"canStart": true,
"blockedBy": null,
"expiresAt": "2026-12-01T10:15:00.000Z"
}
# 2. Start with the quote id: the start is refused if the price is no longer this one
curl -s -X POST "$BASE/videos/faceless" \
-H "$AUTH" -H "Content-Type: application/json" \
-H "Quote-Id: qt_eyJ3cyI6Ii4uLiJ9.c2lnbmF0dXJl" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"kind":"slideshow","scriptId":"'"$SCRIPT_ID"'"}'Сценарии, ролики, карусели и нарезка делаются не мгновенно. Такие методы отвечают 202 Accepted и возвращают ресурс со статусом. Дальше есть два пути: слушать вебхук (лучше всего) или опрашивать метод получения, пока статус не станет конечным.
| Ресурс | Статусы | Опрашивать |
|---|---|---|
| Сценарий | generating → ready | failed | 2 s |
| Карусель или пост | generating → ready | failed | 3 s |
| Ролик | queued → rendering → montage → ready | failed | cancelled | 10 s |
| Слайд-шоу и мультфильм | как ролик; у мультфильма поле needsApproval | 10 s |
| Контент-план, сериал | generating → ready | failed | 3 s |
| Нарезка клипов | поле project.status | 10 s |
Ссылки videoUrl и coverUrl подписаны и действуют около часа: нужна свежая ссылка, запросите ролик ещё раз. Если ролик не получился, списанные ролики возвращаются автоматически. Мультфильм делается в два шага: сначала дешёвый черновик, потом, когда needsApproval стал true, вы одобряете его методом approveStory (тогда списывается остаток) или останавливаете методом cancelVideo.
Пути указаны относительно базового адреса. {brandId}, {videoId} и прочее это UUID ресурсов. Параметры, поля тела и примеры на карточках читаются из тех же схем, которыми API проверяет запросы. Звёздочкой отмечены обязательные поля. Машинное описание лежит по адресу /api/v1/openapi.json.
/brandsСписок брендов
Параметры запроса:
/brands/{brandId}/ideasИдеи бренда
Параметры запроса:
/brands/{brandId}/ideasДобавить идею
Поля тела:
{
"text": "Как выбрать CRM для небольшой студии"
}/brands/{brandId}/scriptsСценарии бренда
Параметры запроса:
/brands/{brandId}/scriptsСоздать сценарий (асинхронно, бесплатно)
Поля тела:
{
"ideaText": "Три ошибки при выборе подрядчика",
"videoFormat": "reels",
"durationSec": 45
}/scripts/{scriptId}Получить сценарий
/scripts/{scriptId}/cancelОстановить сценарий, который ещё пишется
/brands/{brandId}/avatarsАватары и ИИ-персонажи с уровнями реализма и ценой за минуту
Параметры запроса:
/brands/{brandId}/video-twinСостояние видео-двойника бренда
/brands/{brandId}/voicesГолоса бренда и их состояние
Параметры запроса:
/scripts/{scriptId}/video-quoteЦена ролика с лицом по сценарию
Параметры запроса:
/videosСоздать ролик с лицом из сценария
Цена заранее: GET|POST /scripts/{scriptId}/video-quote
Поля тела:
{
"scriptId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"avatarId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"format": "reels",
"tier": "standard"
}/scripts/{scriptId}/faceless-quoteЦена слайд-шоу или мультфильма по сценарию
Параметры запроса:
/videos/facelessСоздать слайд-шоу или черновик мультфильма
Цена заранее: GET|POST /scripts/{scriptId}/faceless-quote
Поля тела:
{
"kind": "slideshow",
"scriptId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"format": "reels"
}/videos/{videoId}/storyЧерновик слайд-шоу или мультфильма: сцены, герои, этап
/videos/{videoId}/approval-quoteЦена одобрения черновика мультфильма
/videos/{videoId}/story/approveОдобрить черновик мультфильма и снять финал
Цена заранее: GET|POST /videos/{videoId}/approval-quote
/videos/{videoId}Статус и ссылки ролика
/videosСписок роликов
Параметры запроса:
/videos/{videoId}/cancelОстановить ролик, который делается (удержанное возвращается)
/translation/languagesЯзыки, на которые переводится ролик
/videos/{videoId}/translation-quoteЦена перевода готового ролика
Параметры запроса:
/videos/{videoId}/translationsПеревести готовый ролик на другие языки
Цена заранее: GET|POST /videos/{videoId}/translation-quote
Поля тела:
{
"languages": [
"en"
],
"lipSync": true
}/videos/{videoId}/translationsПереводы ролика
Параметры запроса:
/brands/{brandId}/carousels/quoteЦена карусели или поста
/brands/{brandId}/carouselsСоздать карусель или пост (асинхронно)
Цена заранее: GET|POST /brands/{brandId}/carousels/quote
Поля тела:
{
"kind": "carousel",
"source": "text",
"text": "5 причин вести блог для бизнеса",
"slides": 7,
"platform": "instagram"
}/brands/{brandId}/carouselsКарусели и посты бренда
Параметры запроса:
/carousels/{carouselId}Получить карусель или пост
/carousels/{carouselId}/cancelОстановить карусель, которая ещё делается
/brands/{brandId}/clip-projects/quoteЦена нарезки клипов из длинного видео
Параметры запроса:
/brands/{brandId}/clip-projectsНарезка клипов из видео по прямой ссылке на файл
Цена заранее: GET|POST /brands/{brandId}/clip-projects/quote
Поля тела:
{
"url": "https://files.example.com/podcast-12.mp4",
"title": "Выпуск 12"
}/brands/{brandId}/clip-projectsПроекты нарезки бренда
Параметры запроса:
/clip-projects/{projectId}Проект нарезки и его клипы
/clip-projects/{projectId}Остановить и удалить проект нарезки (удержанное возвращается)
/brands/{brandId}/series/quoteЦена контент-плана или сериала с героем
Поля тела:
{
"kind": "hero",
"count": 7,
"hero": {
"avatarId": null,
"premise": "Бариста Маша открывает кофейню в спальном районе",
"production": "slideshow",
"writeScripts": true
}
}/brands/{brandId}/seriesСоздать контент-план или сериал с героем (асинхронно)
Цена заранее: GET|POST /brands/{brandId}/series/quote
Поля тела:
{
"kind": "hero",
"count": 7,
"hero": {
"avatarId": null,
"premise": "Бариста Маша открывает кофейню в спальном районе",
"production": "slideshow",
"writeScripts": true
}
}/brands/{brandId}/seriesКонтент-планы и сериалы бренда
Параметры запроса:
/series/{seriesId}Контент-план или сериал и его пункты
/series/{seriesId}/scripts/quoteЦена сценариев для пунктов плана
Поля тела:
{
"includeCarousels": true
}/series/{seriesId}/scriptsНаписать сценарии (и карусели) для пунктов плана
Цена заранее: GET|POST /series/{seriesId}/scripts/quote
Поля тела:
{
"includeCarousels": true
}/series/{seriesId}Остановить и удалить контент-план или сериал
/brands/{brandId}/accountsПодключённые соцсети
Параметры запроса:
/publicationsЗапланировать или опубликовать
Поля тела:
{
"videoId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
"accountIds": [
"6f5e4d3c-2b1a-4098-8765-4321fedcba09"
],
"scheduledAt": "2026-12-01T09:00:00+03:00",
"caption": "Новый ролик"
}/publicationsСписок публикаций
Параметры запроса:
/publications/{publicationId}Публикация и её статус
/publications/{publicationId}/cancelОтменить запланированную публикацию
/balanceБаланс роликов и действий
/planТариф и что он разрешает
/usageРасход за 30 дней и сроки роликов
/topup-quoteЦена докупки роликов на тарифе (только чтение)
Параметры запроса:
/brands/{brandId}/analyticsАналитика бренда
Параметры запроса:
export MAA_API_KEY="maa_live_..."
BASE=""
AUTH="Authorization: Bearer $MAA_API_KEY"
# 1. Brands: take an id
curl -s "$BASE/brands" -H "$AUTH"
# 2. Create a script (async, 202 Accepted)
curl -s -X POST "$BASE/brands/$BRAND_ID/scripts" \
-H "$AUTH" -H "Content-Type: application/json" \
-d '{"ideaText":"Три ошибки при выборе подрядчика","videoFormat":"reels"}'
# 3. Poll until "status" is "ready"
curl -s "$BASE/scripts/$SCRIPT_ID" -H "$AUTH"
# 4. Create a video. The Idempotency-Key makes a retry safe
curl -s -X POST "$BASE/videos" \
-H "$AUTH" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"scriptId":"'"$SCRIPT_ID"'"}'
# 5. Poll the video; when "status" is "ready", "videoUrl" is a signed link
curl -s "$BASE/videos/$VIDEO_ID" -H "$AUTH"Один сценарий оболочки проходит весь путь без кабинета. Нужны curl и jq, ключ с разрешениями content:read, content:write, videos:create и publish, готовый аватар и подключённая соцсеть.
export MAA_API_KEY="maa_live_..."
BASE=""
AUTH="Authorization: Bearer $MAA_API_KEY"
JSON="Content-Type: application/json"
# 1. The brand
BRAND_ID=$(curl -s "$BASE/brands" -H "$AUTH" | jq -r '.data[0].id')
# 2. Idea -> script (free, async)
SCRIPT_ID=$(curl -s -X POST "$BASE/brands/$BRAND_ID/scripts" -H "$AUTH" -H "$JSON" \
-d '{"ideaText":"Три ошибки при выборе подрядчика","videoFormat":"reels"}' | jq -r '.id')
until [ "$(curl -s "$BASE/scripts/$SCRIPT_ID" -H "$AUTH" | jq -r '.status')" = "ready" ]; do sleep 2; done
# 3. Who speaks: an avatar that can talk (each lists its realism levels and the price per started minute)
AVATAR_ID=$(curl -s "$BASE/brands/$BRAND_ID/avatars" -H "$AUTH" \
| jq -r '[.data[] | select(.canTalk and .status == "ready")][0].id')
# 4. The price, then the video with that quote
QUOTE_ID=$(curl -s "$BASE/scripts/$SCRIPT_ID/video-quote?tier=standard" -H "$AUTH" | jq -r '.quoteId')
VIDEO_ID=$(curl -s -X POST "$BASE/videos" -H "$AUTH" -H "$JSON" \
-H "Quote-Id: $QUOTE_ID" -H "Idempotency-Key: $(uuidgen)" \
-d '{"scriptId":"'"$SCRIPT_ID"'","avatarId":"'"$AVATAR_ID"'"}' | jq -r '.id')
# 5. Wait for the video.ready webhook, or poll
until [ "$(curl -s "$BASE/videos/$VIDEO_ID" -H "$AUTH" | jq -r '.status')" = "ready" ]; do sleep 10; done
# 6. Publish to a connected account
ACCOUNT_ID=$(curl -s "$BASE/brands/$BRAND_ID/accounts" -H "$AUTH" | jq -r '.data[0].id')
curl -s -X POST "$BASE/publications" -H "$AUTH" -H "$JSON" -H "Idempotency-Key: $(uuidgen)" \
-d '{"videoId":"'"$VIDEO_ID"'","accountIds":["'"$ACCOUNT_ID"'"],"scheduledAt":"2026-12-01T09:00:00+03:00"}'Добавьте адрес в «Настройки → API и вебхуки», выберите события и сохраните секрет подписи whsec_… (он показывается один раз). Мы будем отправлять POST с JSON на этот адрес. Кнопка «Отправить тест» присылает событие webhook.test, так удобно проверить приём.
| Событие | Когда | Поля data |
|---|---|---|
script.ready | Сценарий готов | scriptId, brandId, title, url |
script.failed | Сценарий не получился | scriptId, brandId, title, url |
video.ready | Ролик готов | videoId, brandId, scriptId, title, format, durationSec, url |
video.failed | Ролик или перевод не получился | videoId, brandId, errorCode, url, sourceVideoId, language |
video.needs_approval | Черновик мультфильма ждёт одобрения | videoId, brandId, scriptId, kind, creditsOnApproval, storyUrl, url |
clip_project.ready | Нарезка готова | projectId, brandId, clipCount, url |
clip_project.failed | Нарезка не получилась | projectId, brandId, errorCode, url |
carousel.ready | Карусель или пост готовы | carouselId, brandId, kind, url |
carousel.failed | Карусель или пост не получились | carouselId, brandId, kind, errorCode, url |
series.ready | Контент-план или сериал готов | seriesId, brandId, kind, title, url |
series.failed | Контент-план или сериал не получился | seriesId, brandId, kind, title, errorCode, url |
publication.published | Публикация вышла | publicationId, brandId, platform, videoId, clipId, carouselId, externalUrl |
publication.failed | Публикация не вышла | publicationId, brandId, platform, videoId, clipId, carouselId, errorCode |
translation.ready | Перевод ролика готов | videoId, brandId, sourceVideoId, language, url |
balance.low | Заканчиваются ролики на балансе | videos, threshold |
Тело каждого запроса это один и тот же конверт; различаются type и data.
{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35", // stable id of the event: dedupe on it
"type": "video.ready", // one of the event types below
"createdAt": "2026-10-15T09:30:12.000Z", // when the event happened (ISO 8601, UTC)
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": { } // fields depend on the type
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "script.ready",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"scriptId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"title": "Три ошибки при выборе подрядчика",
"url": "https://api.example.com/api/v1/scripts/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "script.failed",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"scriptId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"title": "Три ошибки при выборе подрядчика",
"url": "https://api.example.com/api/v1/scripts/3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "video.ready",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"videoId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"scriptId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"title": "Три ошибки при выборе подрядчика",
"format": "reels",
"durationSec": 42,
"url": "https://api.example.com/api/v1/videos/7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "video.failed",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"videoId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"errorCode": "provider.unavailable",
"url": "https://api.example.com/api/v1/videos/7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "video.needs_approval",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"videoId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"scriptId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
"kind": "story",
"creditsOnApproval": 3.5,
"storyUrl": "https://api.example.com/api/v1/videos/7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b/story",
"url": "https://api.example.com/api/v1/videos/7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "clip_project.ready",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"projectId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"clipCount": 8,
"url": "https://api.example.com/api/v1/clip-projects/9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "clip_project.failed",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"projectId": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"errorCode": "clips.no_speech",
"url": "https://api.example.com/api/v1/clip-projects/9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "carousel.ready",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"carouselId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"kind": "carousel",
"url": "https://api.example.com/api/v1/carousels/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "carousel.failed",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"carouselId": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"kind": "carousel",
"errorCode": "provider.unavailable",
"url": "https://api.example.com/api/v1/carousels/2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "series.ready",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"seriesId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"kind": "hero",
"title": "Сериал с героем · 7 серий",
"url": "https://api.example.com/api/v1/series/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "series.failed",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"seriesId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"kind": "hero",
"title": "Сериал с героем · 7 серий",
"errorCode": "provider.unavailable",
"url": "https://api.example.com/api/v1/series/5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "publication.published",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"publicationId": "6f5e4d3c-2b1a-4098-8765-4321fedcba09",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"platform": "telegram",
"videoId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
"clipId": null,
"carouselId": null,
"externalUrl": "https://t.me/yourchannel/123"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "publication.failed",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"publicationId": "6f5e4d3c-2b1a-4098-8765-4321fedcba09",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"platform": "instagram",
"videoId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
"clipId": null,
"carouselId": null,
"errorCode": "publish.account_disconnected"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "translation.ready",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"videoId": "4b5c6d7e-8f9a-4b0c-8d1e-2f3a4b5c6d7e",
"brandId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
"sourceVideoId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
"language": "en",
"url": "https://api.example.com/api/v1/videos/4b5c6d7e-8f9a-4b0c-8d1e-2f3a4b5c6d7e"
}
}{
"id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
"type": "balance.low",
"createdAt": "2026-11-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"videos": 2,
"threshold": 3
}
}{
"id": "evt_test_4c1e9b7a2d6f48e0a35b9c7d1e2f3a40",
"type": "webhook.test",
"createdAt": "2026-10-15T09:30:12.000Z",
"workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
"data": {
"message": "Test event from MAA Studio",
"endpointId": "8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d"
}
}| Заголовок | Значение | Зачем |
|---|---|---|
| X-MAA-Signature | t=<unix>,v1=<hex> | Подпись запроса, проверяйте её. |
| X-MAA-Event | video.ready | Тип события. |
| X-MAA-Event-Id | evt_… | Стабильный id события: по нему отсекайте дубликаты. |
| X-MAA-Delivery | uuid | Id отправки (записи в журнале кабинета). |
POST /webhooks/maa HTTP/1.1
Content-Type: application/json
X-MAA-Signature: t=1790000012,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
X-MAA-Event: video.ready
X-MAA-Event-Id: evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35
X-MAA-Delivery: 1d9c3b52-6a0e-4c2f-9d11-3e8b7a4f5c60Подпись это HMAC-SHA256 от строки "<t>.<сырое тело>" с ключом, равным всему секрету эндпоинта (вместе с префиксом whsec_). Считайте её по сырому телу, как оно пришло: если распарсить JSON и собрать заново, подпись не совпадёт. Сравнивайте за постоянное время и отклоняйте запросы, у которых t старше 5 минут (300 секунд): так перехваченный запрос нельзя проиграть позже.
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SEC = 300; // reject signatures older than 5 minutes
/** rawBody: the request body exactly as received (string), NOT re-serialized JSON. */
export function verifyMaaSignature(rawBody, header, secret) {
const parts = Object.fromEntries((header ?? '').split(',').map((p) => p.trim().split('=', 2)));
const t = Number(parts.t);
const v1 = parts.v1;
if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(v1 ?? '')) return false;
if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SEC) return false;
// The key is the whole secret string, including the "whsec_" prefix
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
// Express: the body must stay raw until the signature is checked
app.post('/webhooks/maa', express.raw({ type: 'application/json' }), (req, res) => {
const raw = req.body.toString('utf8');
if (!verifyMaaSignature(raw, req.get('X-MAA-Signature'), process.env.MAA_WEBHOOK_SECRET)) {
return res.sendStatus(400);
}
const event = JSON.parse(raw);
// Dedupe on event.id (or X-MAA-Event-Id): retries and resends carry the same id
res.sendStatus(200); // answer fast (within 10 s), do the heavy work afterwards
});MCP (Model Context Protocol) позволяет Claude Desktop, Cursor и другим ассистентам вызывать MAA Studio как набор инструментов: «возьми мой бренд, напиши сценарий и запусти ролик». Сервер @maa/mcp работает поверх этого же API и ключа, поэтому действуют те же разрешения, лимиты и списание роликов. Нужен Node.js 22 или новее.
У каждого метода API есть свой инструмент с тем же смыслом. Платные инструменты (выделены) никогда не тратят с первого вызова: без confirm: true инструмент ничего не запускает, а возвращает цену и quoteId. Чтобы запустить, ассистент показывает цену человеку и после согласия вызывает тот же инструмент ещё раз с confirm: true и этим quoteId. Сервер проверяет quoteId: чужой, просроченный или от другого запроса не пройдёт.
Добавьте в claude_desktop_config.json и перезапустите приложение. MAA_API_URL это адрес API-хоста без /api/v1.
{
"mcpServers": {
"maa-studio": {
"command": "npx",
"args": ["-y", "@maa/mcp"],
"env": {
"MAA_API_KEY": "maa_live_...",
"MAA_API_URL": ""
}
}
}
}Файл .cursor/mcp.json в проекте или ~/.cursor/mcp.json для всех проектов.
{
"mcpServers": {
"maa-studio": {
"command": "npx",
"args": ["-y", "@maa/mcp"],
"env": {
"MAA_API_KEY": "maa_live_...",
"MAA_API_URL": ""
}
}
}
}Для общего сервера вместо stdio запустите режим HTTP: сервер слушает POST /mcp.
# Streamable HTTP (POST /mcp): one server, many clients.
# Each client sends its own key in the Authorization: Bearer header.
MAA_API_URL= npx -y @maa/mcp --http --port 3333
# the same through the installed binary
MAA_API_URL= maa-mcp --http --host 127.0.0.1 --port 3333Сейчас действует версия v1 (/api/v1), она стабильна. Внутри v1 мы только добавляем: новые методы, новые необязательные поля запросов, новые поля в ответах, новые типы событий вебхуков и новые значения статусов. Существующие поля не переименовываются и не меняют смысл. Поэтому игнорируйте незнакомые поля и не падайте на неизвестном типе события или статусе. Несовместимые изменения выйдут только в новой версии (/api/v2).