Расписание выгодных часов

GET /v1/off-peak

Возвращает расписание выгодных часов: насколько медленнее расходуется AI-квота компании в каждый час недели и когда наступит ближайшее окно со скидкой.

Скидка применяется к расходу квоты — в выгодные часы один и тот же вызов забирает меньшую долю месячного лимита. Оплата за токены по кошельку скидку не получает. Эндпоинт предназначен для планирования: агент читает расписание и переносит массовые задачи, которые терпят отсрочку, в дешёвые окна.

Параметры

Параметр Тип Обяз. По умолч. Описание
model (query) string нет — Идентификатор модели из `GET /v1/models`. Возвращает расписание этой модели. Без параметра возвращается расписание, отмеченное платформой как основное

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/off-peak?model=bitrix/bitrixgpt-5.5" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/off-peak?model=bitrix/bitrixgpt-5.5" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const url = 'https://vibecode.bitrix24.tech/v1/off-peak?model=bitrix/bitrixgpt-5.5'
const res = await fetch(url, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const schedule = await res.json()

if (schedule.enabled && schedule.currentMultiplier < 1) {
  const discount = Math.round((1 - schedule.currentMultiplier) * 100)
  console.log(`Сейчас выгодный час: квота расходуется на ${discount}% медленнее`)
} else if (schedule.nextWindow) {
  console.log(`Дешевле станет через ${schedule.nextWindow.inHours} ч`)
}

JavaScript — OAuth-приложение

javascript 
const url = 'https://vibecode.bitrix24.tech/v1/off-peak?model=bitrix/bitrixgpt-5.5'
const res = await fetch(url, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const schedule = await res.json()

Поля ответа

Успешный ответ — сам объект расписания, без обёртки success и data.

Поле Тип Описание
enabled boolean Действует ли расписание для запрошенной модели. При false все часы идут по полной цене, остальные поля пустые
timezone string | null Часовой пояс расписания — идентификатор из базы часовых поясов IANA, например Europe/Moscow. По нему считаются день недели и час
currentMultiplier number Множитель расхода квоты в текущий час, больше 0 и не больше 1. Значение 0.5 означает, что квота расходуется вдвое медленнее, значение 1 — без скидки
nextWindow object | null Ближайший час, который строго дешевле текущего, в пределах недели вперёд. null, когда такого часа нет
nextWindow.inHours number Через сколько часов наступит этот час
nextWindow.multiplier number Множитель расхода квоты в этом часе
grid array | null Сетка множителей grid[день][час]. Семь строк по 24 значения. День 0 — воскресенье, день 6 — суббота. Час — от 0 до 23 в часовом поясе timezone
nowCell object | null Ячейка сетки, которой соответствует текущий момент. Считается на сервере, поэтому совпадает с currentMultiplier
nowCell.dow number День недели, от 0 (воскресенье) до 6 (суббота)
nowCell.hour number Час, от 0 до 23

Пример ответа

Расписание действует:

JSON 
{
  "enabled": true,
  "timezone": "Europe/Moscow",
  "currentMultiplier": 1,
  "nextWindow": { "inHours": 4, "multiplier": 0.87 },
  "grid": [
    [0.75, 0.87, 0.87, 0.87, 0.87, 0.87, 0.87, 0.87, 0.75, 0.75, 0.75, 0.75, 0.62, 0.5, 0.75, 0.87, 1, 1, 0.87, 0.87, 0.87, 0.75, 0.75, 0.75],
    [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.62, 0.62, 0.62, 0.62, 0.75, 0.75, 0.87, 0.87, 0.75, 0.75, 0.75, 0.75, 0.62, 0.5, 0.5],
    [0.5, 0.5, 0.62, 0.62, 0.75, 0.62, 0.62, 0.62, 0.75, 0.75, 0.87, 1, 1, 0.87, 0.75, 0.87, 0.87, 0.75, 0.75, 0.62, 0.62, 0.62, 0.62, 0.62],
    [0.75, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.62, 0.62, 0.62, 0.75, 0.75, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0.87],
    [1, 1, 1, 1, 1, 0.87, 0.87, 0.87, 0.87, 1, 1, 1, 1, 1, 1, 0.87, 0.75, 0.75, 0.75, 0.87, 1, 1, 1, 1],
    [1, 1, 1, 1, 1, 0.87, 0.87, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0.87, 0.87, 0.75, 0.87],
    [0.75, 0.62, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.62, 0.75, 0.75, 0.62, 0.62, 0.75, 0.75, 0.87, 0.87, 1, 1, 1, 1, 0.87]
  ],
  "nowCell": { "dow": 4, "hour": 11 }
}

Расписание не действует — у модели его нет, либо выгодные часы отключены на платформе:

JSON 
{
  "enabled": false,
  "timezone": null,
  "currentMultiplier": 1,
  "nextWindow": null,
  "grid": null,
  "nowCell": null
}

Пример ответа при ошибке

401 MISSING_API_KEY — не передан заголовок X-Api-Key:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Ошибки

HTTP Код Описание
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Ключ не найден или отозван
403 scope_missing API-ключу не хватает скоупа vibe:ai
429 rate_limit_exceeded Превышен лимит запросов к AI-эндпоинтам. Время до сброса — в заголовке Retry-After

Полный список общих ошибок API — Ошибки.

Известные особенности

Множитель — коэффициент расхода, а не размер скидки. Значение 0.62 означает, что вызов забирает 62% от той доли квоты, которую он забрал бы без скидки, то есть расход снижен на 38%. Размер скидки считается как 1 - currentMultiplier.

Указывайте модель. Без параметра model эндпоинт отдаёт расписание, отмеченное платформой как основное. Пока основное расписание не назначено, такой вызов возвращает enabled: false, даже если у отдельных моделей скидки действуют.

Неизвестная модель не даёт ошибки. Если у модели нет расписания или идентификатор не существует, приходит 200 с enabled: false и пустыми полями. Признак наличия скидок — поле enabled, а не код ответа.

Расписание меняется. Платформа пересчитывает сетку по фактической нагрузке, поэтому перечитывайте расписание перед планированием, а не сохраняйте его надолго.

nextWindow ищет строго более дешёвый час. Если текущий час уже самый дешёвый в пределах недели вперёд, поле равно null. Это не означает отсутствия скидки — смотрите currentMultiplier.

Скидка замедляет заполнение окон равномерного расходования. Суточное и недельное окна растут на ту же величину расхода, что и месячная квота, то есть уже со скидкой. Перенос отложенных задач в выгодные часы отдаляет и 429 ai_pacing_limited, и исчерпание месячной квоты.

Смотрите также