Управление пресетами

Создавать, менять и удалять пресеты аккаунта через API. Пресет — имя, которое ставится в поле model и подставляет модели, промпт и параметры.

Адрес

Авторизация

Ключ управления с правами presets:read, presets:write

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

Методы

Метод	Право	Что делает
`GET /presets`	`presets:read`	Все пресеты аккаунта, по имени
`POST /presets`	`presets:write`	Создать пресет
`GET /presets/{id}`	`presets:read`	Один пресет
`PATCH /presets/{id}`	`presets:write`	Изменить переданные поля
`DELETE /presets/{id}`	`presets:write`	Удалить пресет

Создать пресет

curl -X POST https://api.aitunnel.ru/v1/aitunnel/presets \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "description": "Ответы поддержки",
    "models": ["claude-sonnet-4.6", "gpt-5.4-mini"],
    "system_prompt": "Ты — ассистент поддержки. Отвечай кратко.",
    "temperature": 0.2,
    "max_tokens": 1024,
    "cache_control": { "type": "ephemeral", "ttl": "1h" },
    "provider": { "sort": "price" }
  }'

Ответ 201 — пресет целиком:

JSON

{
  "id": 318,
  "name": "support-bot",
  "description": "Ответы поддержки",
  "models": ["claude-sonnet-4.6", "gpt-5.4-mini"],
  "system_prompt": "Ты — ассистент поддержки. Отвечай кратко.",
  "temperature": 0.2,
  "top_p": null,
  "frequency_penalty": null,
  "presence_penalty": null,
  "top_k": null,
  "max_tokens": 1024,
  "seed": null,
  "verbosity": null,
  "reasoning_enabled": null,
  "reasoning_effort": null,
  "reasoning_max_tokens": null,
  "reasoning_exclude": null,
  "web_search": null,
  "cache_control": { "type": "ephemeral", "ttl": "1h" },
  "provider": { "sort": "price" },
  "service_tier": null,
  "stop": null,
  "response_format": null,
  "override": true,
  "created_at": "2026-11-14T13:16:00.000Z",
  "updated_at": "2026-11-14T13:16:00.000Z"
}

Обязательны name и models. Всё остальное по умолчанию null: пресет этот параметр не задаёт, и запрос сохраняет свой.
Пресет работает сразу: запрос с "model": "support-bot" уйдёт в claude-sonnet-4.6 с этим промптом и параметрами.
Есть ли модель в каталоге, при сохранении не проверяется: на неизвестную модель ответит сам запрос.
В аккаунте — до 50 пресетов.

Поля пресета

Одни и те же поля принимаются в запросе и приходят в ответе. Поле, которого метод не знает, — ошибка 400.

Поле	Смысл
`id`	Номер пресета, для путей `/presets/{id}`
`name`	Имя, которым пресет вызывается в поле `model`. Латинские буквы, цифры, точка, дефис и подчёркивание; начинается с буквы или цифры; до 64 символов. Имя модели каталога занять нельзя. Обязательно
`description`	Заметка для себя, до 256 символов
`models`	От 1 до 5 моделей: первая основная, остальные запасные по порядку. Обязательно
`system_prompt`	Системный промпт, до 20 000 символов
`temperature`, `top_p`	От 0 до 2 и от 0 до 1
`frequency_penalty`, `presence_penalty`	От −2 до 2
`top_k`, `max_tokens`, `seed`	Целые числа; `max_tokens` — до 1 000 000
`verbosity`	`low`, `medium` или `high`
`reasoning_enabled`, `reasoning_effort`, `reasoning_max_tokens`, `reasoning_exclude`	Рассуждения: включить, усилие (`minimal`, `low`, `medium`, `high`, `xhigh`), бюджет токенов, скрыть цепочку
`web_search`	Параметры инструмента `aitunnel:web_search`: `engine`, `mode`, `max_results`, `max_uses`, `max_total_results`, `search_context_size`, `max_characters`, `user_location`, `allowed_domains`, `excluded_domains`, `x_search`
`cache_control`	Кеширование промпта: `{ "type": "ephemeral" }`, с `"ttl": "1h"` — на час вместо 5 минут
`provider`	Выбор провайдера: `sort`, `order`, `only`, `ignore`, `allow_fallbacks`, `require_parameters`, `data_collection`, `zdr`, `quantizations`, `preferred_min_throughput`, `preferred_max_latency`
`service_tier`	`flex` или `priority`
`stop`	До 4 стоп-последовательностей по 256 символов
`response_format`	`{ "type": "json_object" }` или `json_schema` с `name`, `strict` и `schema`, как в Chat Completions
`override`	`true` — значения пресета заменяют значения запроса; `false` — только заполняют то, что запрос не задал. По умолчанию `true`
`created_at`, `updated_at`	Когда пресет создан и изменён

Список и один пресет

curl https://api.aitunnel.ru/v1/aitunnel/presets \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx"

Ответ — { "data": [...] } с пресетами в алфавитном порядке имён. GET /presets/{id} возвращает один пресет.

Изменить пресет

PATCH /presets/{id} меняет только переданные поля. null очищает параметр; name и models очистить нельзя. Ответ — пресет целиком.

curl -X PATCH https://api.aitunnel.ru/v1/aitunnel/presets/318 \
  -H "Authorization: Bearer sk-aitunnel-mgmt-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "models": ["claude-sonnet-4.6"],
    "temperature": null
  }'

Изменение действует со следующего запроса, который назовёт пресет. Если пресет переименован, запросы со старым именем перестанут его находить.

Удалить пресет

DELETE /presets/{id} отвечает 204 без тела.

Ошибки

Статус	Смысл
`400`	`invalid_request` — неверное или неизвестное поле. В `error.metadata.fields` — каждое поле с объяснением
`401`	`authentication_failed` — ключа нет, он неверный, отозван или истёк
`403`	`permission_denied` — у ключа нет нужного права, IP не в списке разрешённых или метод вызван API-ключом
`404`	`not_found` — «Пресет не найден»
`409`	`invalid_request` — пресет с таким именем уже есть (в `metadata.fields` — поле `name`) или в аккаунте уже 50 пресетов

409

{
  "error": {
    "code": 409,
    "type": "invalid_request",
    "message": "Пресет с именем «support-bot» уже существует",
    "metadata": {
      "fields": [
        {
          "field": "name",
          "message": "Пресет с именем «support-bot» уже существует"
        }
      ]
    },
    "request_id": "req-0J9fQk2vXc8LrT1mNbZa4e"
  }
}

Создание, изменение и удаление пресета ключом управления видны владельцу в журнале активности.