API и MCP для сторонних сервисов и агентов

Версия API v1. Адрес: https://…/api/v1

Через API и MCP чужие сервисы и ИИ-агенты используют Maxom как инструмент: генерируют картинки, видео и песни, пишут тексты и код (Claude). Оплата в токенах вашего аккаунта, те же модели и настройки, что в приложении.

Быстрый старт

1. Войдите в приложение, откройте Профиль → API и создайте ключ. Он показывается один раз: сохраните его сразу. Вместе с ключом выдаётся секрет для проверки вебхуков.
2. Проверьте баланс:

   curl https://…/api/v1/balance \
     -H "Authorization: Bearer ab_live_ВАШ_КЛЮЧ"

3. Создайте картинку (параметр wait дожидается результата до 55 секунд):

   curl -X POST "https://…/api/v1/images?wait=30" \
     -H "Authorization: Bearer ab_live_ВАШ_КЛЮЧ" \
     -H "Content-Type: application/json" \
     -d '{"prompt": "красное яблоко на белом столе, студийное фото", "model": "fast"}'

4. В ответе будет задача с полем result.images[0].url — ссылка на готовую картинку.

Стоимость зависит от модели и настроек. Узнать её заранее и без списания: POST /estimate. Список моделей и настроек: GET /models (без ключа).

Как устроены задачи

Каждый запрос на генерацию создаёт задачу. Токены списываются сразу; если генерация не удалась или задачу отменили, токены возвращаются.

Как получить результат: (1) параметр ?wait=N при создании или в GET /jobs/{id} ждёт до N секунд; (2) опрашивайте GET /jobs/{id}; (3) укажите webhook_url и получите уведомление (см. ниже).

Идемпотентность. Заголовок Idempotency-Key защищает от двойного списания при повторе запроса: повтор с тем же значением вернёт ту же задачу.

Пример задачи:

{
  "id": "job_...", "object": "job", "type": "image", "status": "completed",
  "created_at": "2026-09-21T18:00:00+00:00", "started_at": "...", "finished_at": "...",
  "cost_tokens": <число списанных токенов>, "refunded": false,
  "request": {"prompt": "...", "model": "fast", "count": 2},
  "result": {"images": [{"url": "https://...", "thumbnail_url": "https://..."}]},
  "error": null
}

Справочник

Все запросы с заголовком Authorization: Bearer ab_live_…, кроме GET /models. Тело — JSON.

POST /images — картинки

Результат: result.images[] с url и thumbnail_url.

POST /videos — видео

Результат: result.video.url. Режим переноса движений по видео-референсу пока недоступен в API.

POST /music — песни и музыка

Результат: result.tracks[] (два варианта: url, cover_url, duration) и result.lyrics.

POST /text — тексты, ответы, код

Результат: result.text, result.usage. Обычно готов за секунды: добавьте ?wait=30.

POST /estimate — смета без списания

Тело как у создания задачи плюс type (image, video, music, text). Ответ: cost_tokens, balance_tokens, enough.

POST /batch — пакет до 100 задач

{"jobs": [{"type": "image", "prompt": "..."}, {"type": "text", "prompt": "..."}]}. Каждая задача создаётся и оплачивается отдельно. Ответ 207: results[] с job или error по каждой; если токены закончились, оставшиеся вернут insufficient_balance.

Задачи и баланс

Вебхуки

Если в запросе указан webhook_url (только https), сервис отправит POST с JSON, когда задача завершится: {"event": "job.completed" | "job.failed" | "job.canceled", "created_at": "...", "job": {…}}. Ответ 2xx считается доставкой; иначе повторы через 1 минуту, 5 минут, 30 минут, 2 часа и 12 часов, всего 6 попыток.

Подпись: заголовок X-AB-Signature: t=<время>,v1=<подпись>, где подпись это HMAC-SHA256 от строки время + "." + тело с секретом вебхуков вашего ключа. Проверка:

import hmac, hashlib

def verify(secret: str, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Проверяйте, что время t не старше нескольких минут.

Ошибки и лимиты

Ошибки всегда в одном формате: {"error": {"code": "...", "message": "..."}}.

Лимиты: 120 запросов в минуту на ключ; 20 одновременно выполняемых задач на ключ (остальные ждут в очереди); до 100 задач в пакете. Нужны другие лимиты — напишите нам.

MCP: подключение агентов

MCP-сервер даёт то же самое агентам (Claude, Cursor и другим клиентам с поддержкой MCP). Адрес: https://…/mcp (streamable HTTP), заголовок Authorization: Bearer ab_live_…. Пример настройки клиента:

{
  "mcpServers": {
    "ai-brigada": {
      "url": "https://…/mcp",
      "headers": {"Authorization": "Bearer ab_live_ВАШ_КЛЮЧ"}
    }
  }
}

Если клиент не умеет заголовки, подключите через мост: npx mcp-remote https://…/mcp --header "Authorization: Bearer ab_live_…".

Инструменты ждут результата до 45 секунд; долгие задачи (видео, песни) возвращают job_id и статус processing, дальше агент вызывает get_job с wait_seconds.

OpenAPI

Машиночитаемое описание: /api/v1/openapi.json (подходит для генерации клиентов и подключения как инструмента к агентам).