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

НАЧАЛО РАБОТЫ

Первый запрос

Подключите AICP к серверу вашего приложения: один адрес API, ключ проекта и имя модели.

1. Создайте проект и ключ

   В кабинете → API-ключи создайте ключ и сохраните секрет. Он показывается один раз. Новый проект начинает с нулевого баланса; бюджет выделяет владелец платформы.

2. Настройте приложение

   Храните ключ в секретах сервера или переменной окружения AICP_API_KEY. В настройках интеграции укажите значения ниже.

Готовая интеграция должна позволять задать Base URL и передать Idempotency-Key. Одного поля «ключ OpenAI» недостаточно. Полная совместимость со всеми методами и параметрами OpenAI не заявлена.

3. Отправьте запрос с сервера

Пример ниже выполняет платный запрос в пределах выделенного бюджета. Здесь он не запускается автоматически.

# AICP_API_KEY уже задан в защищённом окружении сервера.
# Сохраните ID до отправки; не меняйте его при повторе этой операции.
REQUEST_ID="$(uuidgen)"
curl --max-time 40 https://api.tower24.tech/v1/chat/completions   -H "Authorization: Bearer $AICP_API_KEY"   -H "Content-Type: application/json"   -H "Idempotency-Key: $REQUEST_ID"   --data-binary '{
    "model": "aicp-chat",
    "messages": [{"role": "user", "content": "Напиши короткое приветствие для клиента CRM."}],
    "max_tokens": 512
  }' 

Текст результата находится в choices[0].message.content. Сохраните id, статус учёта и стоимость из aicp. Если запрос завершился ошибкой или потерялся ответ, сначала прочитайте правила повторов.

НАЧАЛО РАБОТЫ

Авторизация

Все семь методов /v1/ требуют активный ключ проекта в заголовке:

Authorization: Bearer <AICP_API_KEY>

Ключ определяет проект и доступ к его данным. Его создают в кабинете; пароль кабинета и ключ провайдера для этих запросов не подходят. Секрет нельзя помещать в URL, браузерный JavaScript или публичный репозиторий. Запросы выполняет backend вашего продукта; произвольные браузерные cross-origin запросы не поддерживаются.

В проекте может быть до пяти активных ключей. Ключ действует 90 дней; срок и отзыв видны в кабинете. Отозванный или истёкший ключ возвращает 401 unauthorized. Отзыв не удаляет историю и не отменяет уже начатое исполнение.

СПРАВОЧНИК API

Генерация текста

POST/v1/chat/completions

Один нестриминговый ответ модели. Обязательные заголовки: Authorization, Content-Type: application/json, Idempotency-Key.

Другие поля отклоняются. В частности, temperature, tools, reasoning_effort, вложения и клиентские настройки провайдера не принимаются.

{
  "model": "aicp-chat",
  "messages": [
    {
      "role": "user",
      "content": "Напиши короткое приветствие для клиента CRM."
    }
  ],
  "max_tokens": 512
}

Успешный ответ · HTTP 200

Иллюстрация структуры; значения ID, токенов и стоимости в реальном ответе зависят от запроса.

{
  "id": "request-id",
  "object": "chat.completion",
  "created": 1793690000,
  "model": "aicp-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Здравствуйте! Чем можем помочь?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 4,
    "total_tokens": 14
  },
  "aicp": {
    "executionOutcome": "RESULT_EVIDENCE_SAVED",
    "accounting": "COMMITTED",
    "customerDelivery": "UNCONFIRMED",
    "receiptDigest": "sha256-digest",
    "providerCost": {
      "minor": "11",
      "currency": "USD",
      "scale": 6
    },
    "customerCharge": {
      "minor": "14",
      "currency": "USD",
      "scale": 6
    },
    "margin": {
      "minor": "3",
      "currency": "USD",
      "scale": 6
    },
    "markupBps": "2500",
    "route": {
      "policy": "fixed-safe-v1",
      "provider": "openai",
      "model": "gpt-5-mini-2025-08-07",
      "optimizer": "DISABLED_PENDING_EVALUATION"
    },
    "evaluator": { "status": "NOT_RUN" },
    "synthetic": false
  }
}

customerDelivery: UNCONFIRMED не отменяет COMMITTED: сервер не считает отправку HTTP доказательством, что приложение сохранило ответ. Ошибка 502 также может содержать уже подтверждённый расход — см. ошибки.

СПРАВОЧНИК API

Структурированный JSON

POST/v1/chat/completions

Используйте тот же метод и заголовки. Добавьте response_format; результат остаётся JSON-строкой в choices[0].message.content. Разберите её через JSON.parse после проверки HTTP-статуса.

{
  "model": "aicp-chat",
  "messages": [
    {
      "role": "user",
      "content": "Клиент хочет узнать цену. Определи намерение: pricing, support или other."
    }
  ],
  "max_tokens": 512,
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "crm_intent",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "intent": {
            "type": "string",
            "enum": [
              "pricing",
              "support",
              "other"
            ]
          }
        },
        "required": [
          "intent"
        ],
        "additionalProperties": false
      }
    }
  }
}

Поддерживаемая схема

• type: json_schema, обязательные name, strict: true, schema. Name: 1–64 латинских буквы, цифры, _ или -. Необязательное описание — до 256 символов.
• Корень схемы — object. У каждого object: additionalProperties: false, все properties перечислены в required.
• Типы: object, array, string, number, integer, boolean, null. Nullable-форма: ["string", "null"] и аналогично для других типов.
• Ключевые слова: type, description, properties, required, additionalProperties, items, enum, minItems, maxItems, minimum, maximum. Ограничения должны соответствовать типу; enum содержит 1–64 скалярных значения.
• Весь объект json_schema — до 4096 UTF-8 байт, до 64 узлов, глубина до 6 (корень — 1). Служебные имена свойств __proto__, constructor, prototype запрещены.

$ref, anyOf, регулярные выражения и режим json_object не поддерживаются. Невалидный результат модели не превращается в успешный JSON; проверяйте error и фактический учёт.

СПРАВОЧНИК API

Доступные модели

GET/v1/models

curl --max-time 40 "https://api.tower24.tech/v1/models" \
  -H "Authorization: Bearer $AICP_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "aicp-chat",
      "object": "model",
      "owned_by": "openai",
      "nonProduction": false
    }
  ]
}

Клиент использует стабильный alias aicp-chat, а не имя upstream-модели. Текущий безопасный маршрут закреплён за OpenAI gpt-5-mini-2025-08-07. Каталог всех доступных AICP моделей управляется владельцем платформы и не означает, что умный выбор уже включён: до появления измеримой проверки качества действует fixed-safe-v1. Этот метод сообщает клиентскую конфигурацию; он не выполняет inference и не подтверждает работоспособность провайдера.

СПРАВОЧНИК API

Проект и баланс

GET/v1/workspace

curl --max-time 40 "https://api.tower24.tech/v1/workspace" \
  -H "Authorization: Bearer $AICP_API_KEY"

Доступный баланс равен остатку за вычетом резервов. До исполнения сервер резервирует верхнюю оценку стоимости; достаточный баланс нужен даже при ожидаемом коротком ответе. После подтверждённого учёта списывается фактическая стоимость.

СПРАВОЧНИК API

Расходы и история

GET/v1/usage

curl --max-time 40 "https://api.tower24.tech/v1/usage" \
  -H "Authorization: Bearer $AICP_API_KEY"

Метод возвращает историю вашего проекта без параметров пагинации. providerCost — стоимость провайдера, customerCharge — расход клиента, margin — их точная разница по зафиксированной для запроса наценке. Формат денег: {"minor":"11","currency":"USD","scale":6} означает $0.000011. Храните значения точно, без округления до центов.

Стоимость рассчитывает AICP. Продукту-потребителю не нужно повторно вычислять или списывать её по своему тарифу. Отсутствие записи в data ещё не доказывает отсутствие исполнения: проверьте requests и возможный резерв.

СПРАВОЧНИК API

Статус запроса

GET/v1/requests/{id}

id берётся из ответа генерации или error.requestId. В URL передавайте его как один закодированный сегмент. Чужой или неизвестный ID возвращает 404.

curl --max-time 40 "https://api.tower24.tech/v1/requests/REQUEST_ID" \
  -H "Authorization: Bearer $AICP_API_KEY"

Метод возвращает статус и доказательства учёта, не текст генерации. Сохранённый ответ COMMITTED получают повтором исходного POST с тем же телом и Idempotency-Key.

СПРАВОЧНИК API

Завершение учёта

POST/v1/requests/{id}/reconcile

Применяется к SETTLEMENT_PENDING, когда результат уже сохранён, но учёт не завершён. Авторизация — ключ того же проекта, Content-Type — application/json, тело — {}. Idempotency-Key здесь не требуется.

curl --max-time 40 -X POST https://api.tower24.tech/v1/requests/REQUEST_ID/reconcile   -H "Authorization: Bearer $AICP_API_KEY"   -H "Content-Type: application/json"   --data '{}' 

HTTP 200: {"request": {…}, "executorInvoked": false, "nonProduction": false}. Поля request описаны выше. Повтор уже COMMITTED не списывает второй раз. Для UNKNOWN без сохранённого подтверждения — 409 receipt_required; этот метод не снимает неопределённость и не запускает модель заново.

СПРАВОЧНИК API

Отзыв текущего ключа

POST/v1/keys/current/revoke

Отзывает именно ключ, переданный в Authorization. Content-Type — application/json; тело — {}. Idempotency-Key не требуется. Для управления другими ключами используйте кабинет.

# Выполняйте только если хотите отозвать используемый ключ.
curl --max-time 40 -X POST https://api.tower24.tech/v1/keys/current/revoke   -H "Authorization: Bearer $AICP_API_KEY"   -H "Content-Type: application/json"   --data '{}' 

HTTP 200: {"status":"REVOKED","credentialId":"…","nonProduction":false}. Последующие запросы с этим ключом, включая повтор отзыва, получат 401. История сохраняется; уже начатые запросы этим действием не отменяются.

ПРАВИЛА И ОШИБКИ

Повторы и неопределённый результат

Idempotency-Key обязателен для генерации. Используйте 1–128 символов из A–Z a–z 0–9 . _ : -. Для новой операции — новый ID; для повтора той же операции — прежний ID и прежнее тело. Сохраните их до отправки.

То же значение ключа с другим нормализованным телом даёт 409 idempotency_conflict. Все состояния, кроме COMMITTED, не возвращают успешный replay. Автоматические SDK retries и fallback следует отключить; интеграция должна обрабатывать эти состояния явно.

Если ответ потерян и requestId неизвестен, сохраните исходные Idempotency-Key и тело. Чтения GET по Idempotency-Key сейчас нет. Повтор с прежним ключом защищён от второго исполнения; новый ключ такой защиты для исходной операции не даёт. HTTP-таймаут не доказывает отсутствие расходов.

ПРАВИЛА И ОШИБКИ

Ограничения

Текущий публичный Gateway поддерживает текст и строгий JSON. Streaming, tools, embeddings, изображения, аудио, batch и Responses API пока отсутствуют.

Контекст не обрезается незаметно: превышение отклоняется. После UNKNOWN удержанный запрос может занять единственный слот проекта; немедленные повторы не решают эту ситуацию.

ПРАВИЛА И ОШИБКИ

Ошибки API

Проверяйте HTTP-статус и error.code. Текст message может меняться и сейчас может быть на английском. В ответе может присутствовать error.requestId.

{
  "error": {
    "code": "outcome_unknown",
    "message": "Execution outcome is unknown; the hold is retained and this key cannot trigger a retry",
    "requestId": "request-id"
  }
}

При обращении к владельцу платформы передайте время, requestId (если известен), HTTP-статус и error.code. API-ключ и содержимое переписки в сообщение не включайте.