Документация · v1

API для разработчиков

Подключайте MAA Studio к своим сервисам: сценарии, ролики с цифровым двойником, карусели и публикации через REST API, вебхуки и MCP.

REST · JSONBearer maa_live_…WebhooksMCP

Обзор

Публичный API MAA Studio

REST API на JSON проходит весь путь без кабинета: идея, сценарий, ролик с лицом, слайд-шоу или мультфильм, сериал с героем, перевод, нарезка клипов, карусели и публикация в соцсети. У каждого платного запуска есть метод, который заранее говорит цену, ту же, что показывает кабинет. О готовности мы сообщаем вебхуком, поэтому опрашивать API постоянно не нужно.

API входит в тарифы «Эксперт» и «Агентство». Ключи создаёт владелец или администратор пространства в разделе «Настройки → API и вебхуки».
Авторизация

Ключ в заголовке Authorization

Каждый запрос подписывается ключом вида maa_live_… в заголовке Authorization: Bearer. Ключ принадлежит одному пространству и видит только его данные. Полностью ключ показывается один раз при создании, дальше в кабинете виден только его префикс. Храните ключ на сервере: в мобильном приложении, браузере и публичном репозитории ему не место.

Authorization: Bearer maa_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Разрешения ключа (scopes)

Ключу выдаются только нужные разрешения. Запрос к методу, на который у ключа нет разрешения, вернёт 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.

Базовый адрес

Всё под /api/v1

Запросы и ответы в JSON (Content-Type: application/json), время в ISO 8601 (UTC), идентификаторы это UUID. Точный адрес вашего API-хоста показан в кабинете, в разделе «API и вебхуки».

Лимиты

Лимиты запросов

Лимит считается отдельно для каждого ключа, окном в одну минуту.

Лимиты запросов по тарифам
ТарифЗапросов в минутуПлатных запусков в минуту
«Эксперт»12010
«Агентство»60030

Платные запуски (в справочнике они помечены «списывает») считаются по отдельному, более строгому лимиту. Каждый ответ содержит заголовки 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"
  }
}
Коды ошибок
codeHTTPКогда
invalid_api_key401Ключ не передан, неверен или отозван.
plan_required402Тариф пространства не включает API.
insufficient_scope403У ключа нет нужного разрешения.
forbidden403Нет доступа к этому ресурсу.
not_found404Ресурса нет или он принадлежит другому пространству.
validation_error400Запрос не прошёл проверку: смотрите message и details.
rate_limited429Слишком много запросов, смотрите Retry-After.
insufficient_balance402На балансе не хватает роликов или действий. Ничего не списано.
idempotency_conflict409Этот Idempotency-Key уже использован с другим запросом.
idempotency_in_progress409Первый запрос с этим ключом ещё выполняется, повторите чуть позже.
quote_invalid400Quote-Id не принадлежит этому пространству. Запросите цену заново. Ничего не списано.
quote_expired409Цена запрошена больше 15 минут назад. Запросите её заново. Ничего не списано.
quote_mismatch409Цена была запрошена для другой операции или других параметров. Запросите цену именно этого запроса. Ничего не списано.
quote_price_changed409Цена изменилась с момента запроса. Запросите её заново. Ничего не списано.
internal_error500Ошибка на нашей стороне. Повторите запрос; если не помогло, напишите в поддержку.
provider_unavailable503Сервис, от которого мы зависим, временно недоступен. Повторите позже.
video.qc_failed422Ролик не прошёл автоматическую проверку, и мы его не отдали. Ролики вернулись на баланс.
content_rejected422Содержимое не прошло модерацию.
story.plan_required402Мультфильмы не входят в тариф пространства. Ничего не списано.
series.hero_plan_required402Сериал с героем не входит в тариф пространства. Ничего не списано.
series.episodes_limit402На этом тарифе в сериале меньше серий. Ничего не списано.
realism.twin_required409Для этого уровня нужен видео-двойник бренда. Запишите его в кабинете. Ничего не списано.
realism.twin_not_ready409Видео-двойник ещё не готов: идёт подготовка или ждём согласия. Ничего не списано.
realism.photo_required400Видео-двойник работает только на уровнях premium и max. Для standard выберите аватар по фото. Ничего не списано.
realism.engine_unavailable409Этот уровень недоступен для этого видео-двойника. Выберите другой. Ничего не списано.
realism.level_not_connected409Этот уровень для аватара по фото пока не подключён. Выберите standard. Ничего не списано.
avatar.not_talking400Этот образ в полный рост, он не говорит. Выберите аватар, у которого canTalk равно true. Ничего не списано.
studio.unavailable503Этот вид ролика пока не подключён. Ничего не списано.
story.too_long400Сценарий не подходит к этому формату по длине. Сократите его или выберите другой формат. Ничего не списано.
story.unsafe400В истории есть то, что мы не снимаем: сбор денег, вред себе или откровенные сцены. Ничего не списано.
story.wrong_phase409Черновик не ждёт одобрения: он уже одобрен, отменён или ещё готовится.
story.busy409Сейчас перерисовывается кадр или герой. Одобрите через минуту.
series.hero_not_synthetic400Героем сериала или мультфильма может быть только ИИ-персонаж, а не двойник человека. Ничего не списано.
series.wrong_state409Сериал сейчас пересобирается. Повторите через минуту.
action.wrong_state409Статус уже изменился: останавливать или отменять нечего. Прочитайте ресурс ещё раз.
delete.scheduled409На это назначены публикации. Сначала отмените их.
delete.in_progress409Это ещё делается. Сначала остановите.
clips.platform_unsupported400Ссылки на страницы видеоплощадок и соцсетей скачать нельзя. Нужна прямая ссылка на файл.
clips.url_invalid400Ссылка не похожа на публичный адрес http или https.
clips.url_unreachable400Файл по ссылке не скачался.
clips.not_media400По ссылке не видео со звуком.
clips.too_long400Видео длиннее, чем мы принимаем.
clips.too_large400Файл больше, чем мы принимаем.
Списки

Постраничная выдача

Списки принимают 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"'"}'
  • Сценарий пишется бесплатно. Публикация тоже ничего не списывает.
  • У нарезки клипов точная цена известна только после загрузки исходника: 1 ролик за каждые начатые 30 минут. Метод цены отвечает правилом и верхней границей, а если передать длину, то и точной ценой для неё.
  • Докупить ролики через API нельзя. Метод цены докупки только показывает сумму, а платит человек на странице оплаты в кабинете.
  • Двойника человека и клон голоса через API создать нельзя: для них нужна запись согласия, это делается в кабинете. API отдаёт только их состояние.
Асинхронность

Долгие операции и опрос

Сценарии, ролики, карусели и нарезка делаются не мгновенно. Такие методы отвечают 202 Accepted и возвращают ресурс со статусом. Дальше есть два пути: слушать вебхук (лучше всего) или опрашивать метод получения, пока статус не станет конечным.

Статусы ресурсов
РесурсСтатусыОпрашивать
Сценарийgenerating → ready | failed2 s
Карусель или постgenerating → ready | failed3 s
Роликqueued → rendering → montage → ready | failed | cancelled10 s
Слайд-шоу и мультфильмкак ролик; у мультфильма поле needsApproval10 s
Контент-план, сериалgenerating → ready | failed3 s
Нарезка клиповполе project.status10 s

Ссылки videoUrl и coverUrl подписаны и действуют около часа: нужна свежая ссылка, запросите ролик ещё раз. Если ролик не получился, списанные ролики возвращаются автоматически. Мультфильм делается в два шага: сначала дешёвый черновик, потом, когда needsApproval стал true, вы одобряете его методом approveStory (тогда списывается остаток) или останавливаете методом cancelVideo.

Справочник

Методы API

Пути указаны относительно базового адреса. {brandId}, {videoId} и прочее это UUID ресурсов. Параметры, поля тела и примеры на карточках читаются из тех же схем, которыми API проверяет запросы. Звёздочкой отмечены обязательные поля. Машинное описание лежит по адресу /api/v1/openapi.json.

GET/brands

Список брендов

разрешение: content:readуспех: 200MCP: list_brands

Параметры запроса:

  • limit integer
  • cursor string
GET/brands/{brandId}/ideas

Идеи бренда

разрешение: content:readуспех: 200MCP: list_ideas

Параметры запроса:

  • limit integer
  • cursor string
POST/brands/{brandId}/ideas

Добавить идею

разрешение: content:writeуспех: 200Idempotency-KeyMCP: create_idea

Поля тела:

  • text * string
  • segment string
  • stage reach | trust | sale
{
  "text": "Как выбрать CRM для небольшой студии"
}
GET/brands/{brandId}/scripts

Сценарии бренда

разрешение: content:readуспех: 200MCP: list_scripts

Параметры запроса:

  • limit integer
  • cursor string
  • status generating | ready | failed
POST/brands/{brandId}/scripts

Создать сценарий (асинхронно, бесплатно)

разрешение: content:writeуспех: 202Idempotency-KeyMCP: create_script

Поля тела:

  • ideaId string (uuid)
  • ideaText string
  • format story | insight | steps | myth | auto
  • videoFormat reels | shorts | long | square
  • durationSec integer
  • cta string
  • ctaVerbatim boolean
  • mustMention string
  • rules string
{
  "ideaText": "Три ошибки при выборе подрядчика",
  "videoFormat": "reels",
  "durationSec": 45
}
GET/scripts/{scriptId}

Получить сценарий

разрешение: content:readуспех: 200MCP: get_script
POST/scripts/{scriptId}/cancel

Остановить сценарий, который ещё пишется

разрешение: content:writeуспех: 200MCP: cancel_script
GET/brands/{brandId}/avatars

Аватары и ИИ-персонажи с уровнями реализма и ценой за минуту

разрешение: content:readуспех: 200MCP: list_avatars

Параметры запроса:

  • limit integer
  • cursor string
GET/brands/{brandId}/video-twin

Состояние видео-двойника бренда

разрешение: avatars:readуспех: 200MCP: get_video_twin
GET/brands/{brandId}/voices

Голоса бренда и их состояние

разрешение: avatars:readуспех: 200MCP: list_voices

Параметры запроса:

  • limit integer
  • cursor string
GET/scripts/{scriptId}/video-quote

Цена ролика с лицом по сценарию

разрешение: content:readуспех: 200MCP: quote_video

Параметры запроса:

  • format reels | shorts | long | square
  • tier standard | premium | max
  • speaker photo | video_twin
POST/videos

Создать ролик с лицом из сценария

разрешение: videos:createуспех: 202списывает роликиIdempotency-KeyQuote-IdMCP: create_video

Цена заранее: GET|POST /scripts/{scriptId}/video-quote

Поля тела:

  • scriptId * string (uuid)
  • avatarId string (uuid)
  • format reels | shorts | long | square
  • tier standard | premium | max
  • speaker photo | video_twin
{
  "scriptId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "avatarId": "0a1b2c3d-4e5f-4a6b-8c7d-112233445566",
  "format": "reels",
  "tier": "standard"
}
GET/scripts/{scriptId}/faceless-quote

Цена слайд-шоу или мультфильма по сценарию

разрешение: content:readуспех: 200MCP: quote_faceless_video

Параметры запроса:

  • kind * slideshow | story
  • format reels | shorts | long | square
  • autoApprove true | false
POST/videos/faceless

Создать слайд-шоу или черновик мультфильма

разрешение: videos:createуспех: 202списывает роликиIdempotency-KeyQuote-IdMCP: create_faceless_video

Цена заранее: GET|POST /scripts/{scriptId}/faceless-quote

Поля тела:

  • kind * any
  • scriptId * string (uuid)
  • format reels | shorts | long | square
  • heroAvatarId string (uuid)
  • voice object
  • music calm | upbeat | none
  • styleId paper-cut | watercolor-book | ink-sketch | flat-geometric | clay-stopmotion | retro-cel | linocut | pastel-chalk | graphic-novel | folk-gouache
  • characterIds array
  • factCheckUrl string (uri)
  • autoApprove boolean
{
  "kind": "slideshow",
  "scriptId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e6f",
  "format": "reels"
}
GET/videos/{videoId}/story

Черновик слайд-шоу или мультфильма: сцены, герои, этап

разрешение: content:readуспех: 200MCP: get_story
GET/videos/{videoId}/approval-quote

Цена одобрения черновика мультфильма

разрешение: content:readуспех: 200MCP: quote_story_approval
POST/videos/{videoId}/story/approve

Одобрить черновик мультфильма и снять финал

разрешение: videos:createуспех: 202списывает роликиIdempotency-KeyQuote-IdMCP: approve_story

Цена заранее: GET|POST /videos/{videoId}/approval-quote

GET/videos/{videoId}

Статус и ссылки ролика

разрешение: content:readуспех: 200MCP: get_video
GET/videos

Список роликов

разрешение: content:readуспех: 200MCP: list_videos

Параметры запроса:

  • limit integer
  • cursor string
  • brandId string (uuid)
  • status queued | rendering | montage | ready | failed | cancelled
POST/videos/{videoId}/cancel

Остановить ролик, который делается (удержанное возвращается)

разрешение: videos:createуспех: 200MCP: cancel_video
GET/translation/languages

Языки, на которые переводится ролик

разрешение: content:readуспех: 200MCP: list_translation_languages
GET/videos/{videoId}/translation-quote

Цена перевода готового ролика

разрешение: content:readуспех: 200MCP: quote_translation

Параметры запроса:

  • languages * string
  • lipSync true | false
POST/videos/{videoId}/translations

Перевести готовый ролик на другие языки

разрешение: translationsуспех: 202списывает роликиIdempotency-KeyQuote-IdMCP: translate_video

Цена заранее: GET|POST /videos/{videoId}/translation-quote

Поля тела:

  • languages * array
  • lipSync boolean
{
  "languages": [
    "en"
  ],
  "lipSync": true
}
GET/videos/{videoId}/translations

Переводы ролика

разрешение: content:readуспех: 200MCP: list_translations

Параметры запроса:

  • limit integer
  • cursor string
GET/brands/{brandId}/carousels/quote

Цена карусели или поста

разрешение: content:readуспех: 200MCP: quote_carousel
POST/brands/{brandId}/carousels

Создать карусель или пост (асинхронно)

разрешение: carouselsуспех: 202списывает действияIdempotency-KeyQuote-IdMCP: create_carousel

Цена заранее: GET|POST /brands/{brandId}/carousels/quote

Поля тела:

  • kind * carousel | post
  • source * idea | script | video | text
  • sourceId string (uuid)
  • text string
  • slides integer
  • platform instagram | vk | telegram | linkedin | threads | universal
  • tone expert | friendly | bold | mentor
  • design object
{
  "kind": "carousel",
  "source": "text",
  "text": "5 причин вести блог для бизнеса",
  "slides": 7,
  "platform": "instagram"
}
GET/brands/{brandId}/carousels

Карусели и посты бренда

разрешение: carouselsуспех: 200MCP: list_carousels

Параметры запроса:

  • limit integer
  • cursor string
GET/carousels/{carouselId}

Получить карусель или пост

разрешение: carouselsуспех: 200MCP: get_carousel
POST/carousels/{carouselId}/cancel

Остановить карусель, которая ещё делается

разрешение: carouselsуспех: 200MCP: cancel_carousel
GET/brands/{brandId}/clip-projects/quote

Цена нарезки клипов из длинного видео

разрешение: content:readуспех: 200MCP: quote_clips

Параметры запроса:

  • durationSec integer
POST/brands/{brandId}/clip-projects

Нарезка клипов из видео по прямой ссылке на файл

разрешение: clipsуспех: 202списывает роликиIdempotency-KeyQuote-IdMCP: find_clips

Цена заранее: GET|POST /brands/{brandId}/clip-projects/quote

Поля тела:

  • url * string (uri)
  • title string
  • settings object
{
  "url": "https://files.example.com/podcast-12.mp4",
  "title": "Выпуск 12"
}
GET/brands/{brandId}/clip-projects

Проекты нарезки бренда

разрешение: clipsуспех: 200MCP: list_clip_projects

Параметры запроса:

  • limit integer
  • cursor string
GET/clip-projects/{projectId}

Проект нарезки и его клипы

разрешение: clipsуспех: 200MCP: get_clip_project
DELETE/clip-projects/{projectId}

Остановить и удалить проект нарезки (удержанное возвращается)

разрешение: clipsуспех: 200MCP: delete_clip_project
POST/brands/{brandId}/series/quote

Цена контент-плана или сериала с героем

разрешение: content:readуспех: 200MCP: quote_series

Поля тела:

  • title string
  • count integer
  • cadence object
  • mix object
  • startAt string (date-time)
  • useTrends boolean
  • theme string
  • kind plan | hero
  • hero object
{
  "kind": "hero",
  "count": 7,
  "hero": {
    "avatarId": null,
    "premise": "Бариста Маша открывает кофейню в спальном районе",
    "production": "slideshow",
    "writeScripts": true
  }
}
POST/brands/{brandId}/series

Создать контент-план или сериал с героем (асинхронно)

разрешение: seriesуспех: 202списывает действияIdempotency-KeyQuote-IdMCP: create_series

Цена заранее: GET|POST /brands/{brandId}/series/quote

Поля тела:

  • title string
  • count integer
  • cadence object
  • mix object
  • startAt string (date-time)
  • useTrends boolean
  • theme string
  • kind plan | hero
  • hero object
{
  "kind": "hero",
  "count": 7,
  "hero": {
    "avatarId": null,
    "premise": "Бариста Маша открывает кофейню в спальном районе",
    "production": "slideshow",
    "writeScripts": true
  }
}
GET/brands/{brandId}/series

Контент-планы и сериалы бренда

разрешение: seriesуспех: 200MCP: list_series

Параметры запроса:

  • limit integer
  • cursor string
GET/series/{seriesId}

Контент-план или сериал и его пункты

разрешение: seriesуспех: 200MCP: get_series
POST/series/{seriesId}/scripts/quote

Цена сценариев для пунктов плана

разрешение: content:readуспех: 200MCP: quote_series_scripts

Поля тела:

  • includeCarousels boolean
  • itemIndexes array
{
  "includeCarousels": true
}
POST/series/{seriesId}/scripts

Написать сценарии (и карусели) для пунктов плана

разрешение: seriesуспех: 202списывает действияIdempotency-KeyQuote-IdMCP: write_series_scripts

Цена заранее: GET|POST /series/{seriesId}/scripts/quote

Поля тела:

  • includeCarousels boolean
  • itemIndexes array
{
  "includeCarousels": true
}
DELETE/series/{seriesId}

Остановить и удалить контент-план или сериал

разрешение: seriesуспех: 200MCP: delete_series
GET/brands/{brandId}/accounts

Подключённые соцсети

разрешение: publishуспех: 200MCP: list_accounts

Параметры запроса:

  • limit integer
  • cursor string
POST/publications

Запланировать или опубликовать

разрешение: publishуспех: 200Idempotency-KeyMCP: schedule_publication

Поля тела:

  • videoId string (uuid)
  • clipId string (uuid)
  • carouselId string (uuid)
  • accountIds * array
  • scheduledAt string (date-time)
  • caption string
{
  "videoId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
  "accountIds": [
    "6f5e4d3c-2b1a-4098-8765-4321fedcba09"
  ],
  "scheduledAt": "2026-12-01T09:00:00+03:00",
  "caption": "Новый ролик"
}
GET/publications

Список публикаций

разрешение: publishуспех: 200MCP: list_publications

Параметры запроса:

  • limit integer
  • cursor string
  • brandId string (uuid)
  • status scheduled | publishing | published | failed | cancelled
  • from string (date-time)
  • to string (date-time)
GET/publications/{publicationId}

Публикация и её статус

разрешение: publishуспех: 200MCP: get_publication
POST/publications/{publicationId}/cancel

Отменить запланированную публикацию

разрешение: publishуспех: 200MCP: cancel_publication
GET/balance

Баланс роликов и действий

разрешение: content:readуспех: 200MCP: get_balance
GET/plan

Тариф и что он разрешает

разрешение: billing:readуспех: 200MCP: get_plan
GET/usage

Расход за 30 дней и сроки роликов

разрешение: billing:readуспех: 200MCP: get_usage
GET/topup-quote

Цена докупки роликов на тарифе (только чтение)

разрешение: billing:readуспех: 200MCP: quote_topup

Параметры запроса:

  • videos integer
GET/brands/{brandId}/analytics

Аналитика бренда

разрешение: analytics:readуспех: 200MCP: get_analytics

Параметры запроса:

  • days integer
Быстрый старт

От ключа до готового ролика

  1. Создайте ключ с разрешениями content:read, content:write и videos:create.
  2. Возьмите id бренда, создайте сценарий и дождитесь статуса ready.
  3. Создайте ролик с заголовком Idempotency-Key и опрашивайте его до статуса ready.
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"
Создание ролика списывает ролики с баланса. Узнать цену заранее можно методом GET /scripts/{scriptId}/video-quote, а его quoteId передать в заголовке Quote-Id.
Весь путь

Идея, сценарий, ролик, публикация

Один сценарий оболочки проходит весь путь без кабинета. Нужны 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
}
script.ready
{
  "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"
  }
}
script.failed
{
  "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"
  }
}
video.ready
{
  "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"
  }
}
video.failed
{
  "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"
  }
}
video.needs_approval
{
  "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"
  }
}
clip_project.ready
{
  "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"
  }
}
clip_project.failed
{
  "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"
  }
}
carousel.ready
{
  "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"
  }
}
carousel.failed
{
  "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"
  }
}
series.ready
{
  "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"
  }
}
series.failed
{
  "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"
  }
}
publication.published
{
  "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"
  }
}
publication.failed
{
  "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"
  }
}
translation.ready
{
  "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"
  }
}
balance.low
{
  "id": "evt_9f2c4a7e1b3d58606c0a2f4e8b1d7a35",
  "type": "balance.low",
  "createdAt": "2026-11-15T09:30:12.000Z",
  "workspaceId": "5b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d",
  "data": {
    "videos": 2,
    "threshold": 3
  }
}
webhook.test
{
  "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-Signaturet=<unix>,v1=<hex>Подпись запроса, проверяйте её.
X-MAA-Eventvideo.readyТип события.
X-MAA-Event-Idevt_…Стабильный id события: по нему отсекайте дубликаты.
X-MAA-DeliveryuuidId отправки (записи в журнале кабинета).
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
});

Как мы доставляем

  • Успех это любой ответ 2xx. Всё остальное (3xx, 4xx, 5xx, таймаут, обрыв) считается неудачей.
  • Таймаут ответа 10 секунд. Отвечайте сразу, тяжёлую работу делайте после ответа.
  • При неудаче повторяем с нарастающей паузой (30 секунд, 2 минуты, 10 минут, 30 минут, затем часы) примерно до 24 часов с момента первой попытки. Id события при повторах тот же, поэтому дубликаты отсекайте по нему.
  • Порядок доставки не гарантирован: событие, случившееся позже, может прийти раньше.
  • Адрес, который долго не отвечает 2xx, мы выключаем автоматически. В кабинете это видно, после починки адрес включается одной кнопкой.
  • Принимаем только публичные https-адреса. Локальные и внутренние адреса (localhost, 10.x, 192.168.x и подобные) заблокированы.
  • Любую отправку можно повторить вручную из журнала в кабинете: она уйдёт с тем же id события.
MCP

MCP-сервер для ИИ-ассистентов

MCP (Model Context Protocol) позволяет Claude Desktop, Cursor и другим ассистентам вызывать MAA Studio как набор инструментов: «возьми мой бренд, напиши сценарий и запусти ролик». Сервер @maa/mcp работает поверх этого же API и ключа, поэтому действуют те же разрешения, лимиты и списание роликов. Нужен Node.js 22 или новее.

Инструменты

У каждого метода API есть свой инструмент с тем же смыслом. Платные инструменты (выделены) никогда не тратят с первого вызова: без confirm: true инструмент ничего не запускает, а возвращает цену и quoteId. Чтобы запустить, ассистент показывает цену человеку и после согласия вызывает тот же инструмент ещё раз с confirm: true и этим quoteId. Сервер проверяет quoteId: чужой, просроченный или от другого запроса не пройдёт.

  • list_brands
  • list_ideas
  • create_idea
  • list_scripts
  • create_script
  • get_script
  • cancel_script
  • list_avatars
  • get_video_twin
  • list_voices
  • quote_video
  • create_video
  • quote_faceless_video
  • create_faceless_video
  • get_story
  • quote_story_approval
  • approve_story
  • get_video
  • list_videos
  • cancel_video
  • list_translation_languages
  • quote_translation
  • translate_video
  • list_translations
  • quote_carousel
  • create_carousel
  • list_carousels
  • get_carousel
  • cancel_carousel
  • quote_clips
  • find_clips
  • list_clip_projects
  • get_clip_project
  • delete_clip_project
  • quote_series
  • create_series
  • list_series
  • get_series
  • quote_series_scripts
  • write_series_scripts
  • delete_series
  • list_accounts
  • schedule_publication
  • list_publications
  • get_publication
  • cancel_publication
  • get_balance
  • get_plan
  • get_usage
  • quote_topup
  • get_analytics

Claude Desktop

Добавьте в 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

Файл .cursor/mcp.json в проекте или ~/.cursor/mcp.json для всех проектов.

{
  "mcpServers": {
    "maa-studio": {
      "command": "npx",
      "args": ["-y", "@maa/mcp"],
      "env": {
        "MAA_API_KEY": "maa_live_...",
        "MAA_API_URL": ""
      }
    }
  }
}

Streamable HTTP

Для общего сервера вместо 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
Ассистент действует от имени ключа. Для ключа, который отдаёте ассистенту, выдавайте только нужные разрешения. Без videos:create, translations, clips, carousels и series ассистент сможет только читать и считать цену.
Версии

Версионирование

Сейчас действует версия v1 (/api/v1), она стабильна. Внутри v1 мы только добавляем: новые методы, новые необязательные поля запросов, новые поля в ответах, новые типы событий вебхуков и новые значения статусов. Существующие поля не переименовываются и не меняют смысл. Поэтому игнорируйте незнакомые поля и не падайте на неизвестном типе события или статусе. Несовместимые изменения выйдут только в новой версии (/api/v2).

API для разработчиков · MAA Studio